Passkeys Module

The passkeys module (sso.passkeys) provides FIDO2/WebAuthn authentication methods for passwordless login using biometrics (Touch ID, Face ID, Windows Hello) or hardware security keys (YubiKey).

Methods

`sso.passkeys.isSupported()`

Signature:

isSupported(): boolean

Description: Check if WebAuthn is supported in the current browser environment.

Returns: boolean - True if WebAuthn is supported, false otherwise.

Example:

if (sso.passkeys.isSupported()) {
  console.log('Passkeys are supported on this device');
} else {
  console.log('Passkeys not available - show alternative login methods');
}

`sso.passkeys.isPlatformAuthenticatorAvailable()`

Signature:

isPlatformAuthenticatorAvailable(): Promise<boolean>

Description: Check if a platform authenticator (Touch ID, Face ID, Windows Hello) is available on the device. This does not detect external security keys.

Returns: Promise<boolean> - True if platform authenticator is available.

Example:

const hasPlatformAuth = await sso.passkeys.isPlatformAuthenticatorAvailable();
if (hasPlatformAuth) {
  console.log('Can use Touch ID / Face ID / Windows Hello');
}

`sso.passkeys.register()`

Signature:

register(displayName?: string): Promise<string>

Description: Register a new passkey for the authenticated user. This method requires an active JWT session. The browser prompts the user to create a passkey using their device’s authenticator.

Parameters:

Name	Type	Description
displayName	string (optional)	Display name for the passkey (e.g., “My MacBook Pro”)

Returns: Promise<string> - The registered passkey ID.

Example:

try {
  const passkeyId = await sso.passkeys.register('My MacBook Pro');
  console.log('Passkey registered with ID:', passkeyId);
} catch (error) {
  console.error('Passkey registration failed:', error);
}

Throws:

Error - When WebAuthn is not supported in the browser.
SsoApiError - When user is not authenticated or registration fails.

`sso.passkeys.login()`

Signature:

login(
  email: string,
  context?: {
    org_slug?: string;
    service_slug?: string;
    redirect_uri?: string;
  }
): Promise<PasskeyAuthFinishResponse>

Description: Authenticate using a passkey and obtain a JWT session. Hosted-auth flows can scope passkey login to an organization and service so the backend validates the redirect URI before issuing tokens.

Parameters:

Name	Type	Description
email	string	User’s email address
context.org_slug	string (optional)	Organization slug for scoped passkey login
context.service_slug	string (optional)	Service slug for scoped passkey login
context.redirect_uri	string (optional)	Service callback URI validated before redirect-based login completes

Returns: Promise<PasskeyAuthFinishResponse> - Authentication response with JWT token.

Response Fields:

Field	Type	Description
access_token	string	JWT access token
refresh_token	string	Refresh token for automatic session renewal
expires_in	number	Access-token lifetime in seconds
token	string	Backward-compatible alias for `access_token`
user_id	string	Authenticated user’s ID

Example:

try {
  const result = await sso.passkeys.login('user@example.com', {
    org_slug: 'acme-corp',
    service_slug: 'main-app',
    redirect_uri: 'https://app.acme.com/callback'
  });
  await sso.setSession({
    access_token: result.access_token,
    refresh_token: result.refresh_token
  });
  console.log('Logged in as:', result.user_id);
} catch (error) {
  console.error('Passkey login failed:', error);
}

Throws:

Error - When WebAuthn is not supported in the browser.
SsoApiError - When user has no registered passkeys or authentication fails.

`sso.passkeys.list()`

Signature:

list(): Promise<UserPasskey[]>

Description: List the authenticated user’s registered passkeys for account settings and security surfaces.

`sso.passkeys.updateName()`

Signature:

updateName(passkeyId: string, name: string): Promise<UserPasskey>

Description: Rename one of the authenticated user’s passkeys.

`sso.passkeys.delete()`

Signature:

delete(passkeyId: string): Promise<PasskeyActionResponse>

Description: Delete one of the authenticated user’s passkeys.

Example:

const passkeys = await sso.passkeys.list();

if (passkeys.length > 0) {
  const renamed = await sso.passkeys.updateName(passkeys[0].id, 'Work MacBook');
  console.log('Renamed passkey:', renamed.name);

  const result = await sso.passkeys.delete(passkeys[0].id);
  console.log(result.message);
}

Type Definitions

PasskeyAuthFinishResponse

interface PasskeyAuthFinishResponse {
  access_token: string;
  refresh_token: string;
  expires_in: number;
  token: string;
  user_id: string;
}

UserPasskey

interface UserPasskey {
  id: string;
  name: string;
  backup_eligible: boolean;
  backup_state: boolean;
  transports?: string | null;
  last_used_at?: string | null;
  created_at: string;
}

PasskeyActionResponse

interface PasskeyActionResponse {
  success: boolean;
  message: string;
}