@identia/auth-core

Framework-agnostic authentication engine for the Identia CIAM platform. Handles OIDC/PKCE flows, token lifecycle, passkey (WebAuthn) ceremonies, and multi-provider login — all without tying you to React or any other UI framework.

Installation

npm install @identia/auth-core

Quick Start

import { AuthClient } from '@identia/auth-core';

const auth = new AuthClient({
  domain: 'your-tenant.accessiq.app',
  clientId: 'your-client-id',
  redirectUri: window.location.origin + '/callback',
});

// Start login
await auth.login();

// Handle callback (after redirect back)
await auth.handleCallback();

// Get current user
const user = auth.getUser();

Features

| Feature | Description | |---------|-------------| | OIDC + PKCE | Standards-compliant authorization code flow with PKCE | | Token Management | Automatic refresh, expiry detection, and secure storage | | Passkeys / WebAuthn | Registration, login, and key management for passwordless auth | | Multi-Provider | Fetch available login options (email, Google, Microsoft, GitHub, SAML) per tenant | | OAuth Flows | Initiate and complete OAuth with any configured identity provider | | Storage Strategies | localStorage, sessionStorage, or in-memory — configurable per environment | | Event System | Subscribe to auth state changes (login, logout, token_refreshed, error) |

API Reference

AuthClient

The main entry point. Manages the full authentication lifecycle.

const auth = new AuthClient({
  domain: 'tenant.accessiq.app',
  clientId: 'client-id',
  redirectUri: 'https://app.example.com/callback',
  scopes: ['openid', 'profile', 'email'],   // optional, defaults to openid profile email
  storage: 'localStorage',                   // 'localStorage' | 'sessionStorage' | 'memory'
});

await auth.login();                     // Redirect to Identia login
await auth.login({ provider: 'google' }); // Skip login page, go straight to Google
await auth.handleCallback();            // Exchange auth code for tokens
await auth.logout();                    // Clear tokens and redirect to logout endpoint
const user = auth.getUser();            // Current user profile or null
const token = auth.getAccessToken();    // Raw access token string
const isAuth = auth.isAuthenticated();  // boolean

Login Options

Discover which login methods are enabled for a tenant:

import { fetchLoginOptions } from '@identia/auth-core';

const options = await fetchLoginOptions('tenant.accessiq.app');
// { email: true, google: true, microsoft: false, github: true, saml: false, passkeys: { enabled: true } }

Passkeys

import { handlePasskeyRegistration, handlePasskeyLogin, fetchPasskeys } from '@identia/auth-core';

// Register a new passkey
await handlePasskeyRegistration({ domain: 'tenant.accessiq.app', accessToken });

// Login with passkey
const result = await handlePasskeyLogin({ domain: 'tenant.accessiq.app', tenantId });

// List registered passkeys
const keys = await fetchPasskeys({ domain: 'tenant.accessiq.app', accessToken });

JWT Utilities

import { decodeJwtPayload, isTokenExpired, extractUserProfile } from '@identia/auth-core';

const payload = decodeJwtPayload(accessToken);
const expired = isTokenExpired(accessToken);
const profile = extractUserProfile(accessToken);

Events

auth.on('login', (user) => console.log('Logged in:', user));
auth.on('logout', () => console.log('Logged out'));
auth.on('token_refreshed', (tokens) => { /* ... */ });
auth.on('error', (err) => console.error(err));

Related Packages

| Package | Description | |---------|-------------| | @identia/auth-react | React components and hooks built on auth-core | | @identia/sdk | TypeScript SDK for permissions, feature flags, and entitlements | | @identia/react | React bindings for the SDK (feature flags, permissions, guards) |

License

MIT