@acl-identity/browser

Browser client for the ACL Identity SDK. Handles OAuth2 PKCE sign-in/sign-out, WebAuthn passkey authentication, silent token renewal, and user account management.

If you are using React, install @acl-identity/react instead — it includes this package and adds AuthProvider, useAuth, and ready-made UI components.

Installation

npm install @acl-identity/browser
# or
pnpm add @acl-identity/browser

Quick start

import { ACLBrowserClient } from '@acl-identity/browser';

const client = new ACLBrowserClient({
  baseUrl: 'https://auth.example.com',
  clientId: 'my-client-id',
  redirectUri: 'https://app.example.com/callback',
  orgSlug: 'my-org',       // optional, for multi-tenant routing
  autoRefresh: true,        // auto-refresh tokens before expiry
});

Sign in (OAuth2 PKCE)

// 1. Build the authorization URL and redirect the user
const { url, state, codeVerifier } = await client.auth.buildAuthorizationUrl({
  clientId: 'my-client-id',
  redirectUri: 'https://app.example.com/callback',
  scope: 'openid profile email',
});
// store { state, codeVerifier } in sessionStorage, then:
window.location.href = url;

// 2. On the callback page, exchange the code for tokens
await client.auth.exchangeCode(code, codeVerifier, redirectUri);

// 3. Read the current user
const user = await client.auth.parseCurrentUser();
console.log(user?.email);

Sign out

await client.auth.logout({ revokeToken: true });

WebAuthn passkeys

// Authenticate with a passkey (no password)
const tokens = await client.auth.authenticateWithPasskey();

Account management

// User profile
const profile = await client.account.profile.get();
await client.account.profile.update({ displayName: 'Ada Lovelace' });

// Active sessions
const sessions = await client.account.sessions.list();
await client.account.sessions.revoke(sessionId);

// Passkeys
const passkeys = await client.account.passkeys.list();
await client.account.passkeys.delete(credentialId);

// MFA
const status = await client.account.mfa.getStatus();
const setup = await client.account.mfa.setup();
await client.account.mfa.verifySetup('123456');

Configuration

| Option | Type | Description | |---|---|---| | baseUrl | string | Base URL of your ACL Identity server | | clientId | string | OAuth2 client ID | | redirectUri | string | Registered redirect URI | | orgSlug | string | Organization slug for multi-tenant routing | | tokenStorage | TokenStorage | Custom token storage (defaults to localStorage) | | autoRefresh | boolean | Auto-refresh tokens before expiry | | clockSkewMs | number | Clock skew tolerance in milliseconds | | timeout | number | HTTP request timeout in milliseconds | | onTokenExpired | () => void | Called when the session cannot be renewed | | fetchImpl | typeof fetch | Custom fetch implementation (useful for testing) |

License

MIT