Authentication Reference

Passage.js functions for authentication related events

The core component of Passage.js is the authentication functionality. Passage.js provides methods to register and login users via device biometrics, magic links, or one-time codes depending on your auth configuration and the user's device. It also includes a number of helper functions to improve the user experience.

All methods are a part of the Passage class which is instantiated as follows:

import { Passage } from '@passageidentity/passage-js';

const passage = new Passage('YOUR APP ID');
const app = await passage.appInfo();

Authentication Methods

WebAuthn Compatability

.checkWebauthnConfig(appInfo: PassageAppInfo)

This method checks if the app is configured properly to support WebAuthn. Specifically, it checks if the auth origin of the app matches the current domain.

Parameters

appInfo: PassageAppInfo

Returns

boolean

Indicates if the app is configured correct to support WebAuthn.

.isWebauthnSupported(roaming: boolean)

This helper method will check to see if the current device and browser support WebAuthn. This is using the PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() function. If the current browser is Brave, this method will return false. Due to inconsistent WebAuthn support and reporting in Brave, we can't be sure that Passage will work in Brave browsers.

Parameters

roaming: boolean - whether you want to check support for roaming authenticators (e.g. Yubikeys). This should always be false for the time being as Passage does not support roaming authenticators due to a more confusing user experience.

Returns

Promise<boolean>

Boolean indicating if WebAuthn is supported in the current browser context.

Passkey Login & Register

.login(identifier: string)

Prompts a user to login to your app using device biometrics. This functions handles the WebAuthn interactions with Passage and the user's browser and device.

Parameters

identifier: string - email or phone number, depending on your app settings

Returns

Promise<AuthResult>

This method returns a Promise that resolves with an AuthResult object. The AuthResult object contains an authentication token (JWT) and redirect URL. The auth token should be used on all subsequent authenticated requests to the app. The redirect URL specifies the route that users should be redirected to after completed registration or login

interface AuthResult {
  redirect_url: string;
  auth_token: string;
  refresh_token: string; // if refresh tokens are enabled
  refresh_token_expiration: number; // if refresh tokens are enabled
}

.register(identifier: string)

Prompts a user to register for your app using device biometrics. This functions handles the WebAuthn interactions with Passage and the user's browser and device.

Parameters

identifier: string - email or phone number, depending on your app settings

Returns

Promise<AuthResult>

This method returns a Promise that resolves with an AuthResult object. The AuthResult object contains an authentication token (JWT) and redirect URL. The auth token should be used on all subsequent authenticated requests to the app. The redirect URL specifies the route that users should be redirected to after completed registration or login

interface AuthResult {
  redirect_url: string;
  auth_token: string;
  refresh_token: string; // if refresh tokens are enabled
  refresh_token_expiration: number; // if refresh tokens are enabled
}

.appInfo()

Fetches data about an application, specifically the settings that would affect the way that users register and login.

Parameters

None. app_id is passed to the constructor.

Return

Promise<PassageAppInfo>

This method returns a Promise that resolves with a PassageAppInfo object. The PassageAppInfo interface includes all settings for an app.

interface PassageAppInfo {
    name: string;
    id: string;
    auth_origin: string;
    redirect_url: string;
    rsa_public_key: string;
    ephemeral: boolean;
    allowed_identifier: Identifier; // email, phone, or both
    require_email_verification: boolean;
    session_timeout_length: number;
}

.identifierExists(identifier: string)

Checks if the identifier provided exists for the application. This method should be used to determine whether to register or log in a user. This method also checks that the app supports the identifier types (e.g., it will throw an error if a phone number is supplied to an app that only supports emails as an identifier).

Parameters

identifier: string - email or phone number, depending on your app settings

Returns

Promise<PassageUser>

Returns a Promise that resolves with a PassageUser interface. This contains the unauthenticated information about a user, including their status, user ID, and whether or not they have previously signed in with WebAuthn.

interface PassageUser {
    id: string;
    webauthn: boolean;
    status: PassageUserStatus; // active, inactive, or pending
}

.createUser(data: createUserPayload)

Creates a user with the given identifier. The user will be creating with a pending status until they have authenticated for the first time. This method also checks that the app supports the identifier types (e.g., it will throw an error if a phone number is supplied to an app that only supports emails as an identifier).

Parameters

data: createUserPayload - identifier and optional metadata fields for the user

interface CreateUserPayload {
    identifier: string;
    user_metadata?: object;
}

Returns

Promise<PassageUser>

Returns a Promise that resolves with a PassageUser interface. This contains the information about a user, including their status, user ID, and whether or not they have previously signed in with WebAuthn.

interface PassageUser {
    id: string;
    webauthn: boolean;
    status: PassageUserStatus; //pending
    email?: string;
    phone?: string;
    user_metadata?: object | null;
}

Magic Links

.newRegisterMagicLink(identifier: string)

Creates and send a magic link to register the user. The user will receive an email or text to complete the registration.

Parameters

identifier: string - email or phone number, depending on your app settings

Returns

Promise<PassageMagicLinkRequest>

Returns a promise that resolves to a PassageMagicLinkRequest. This type include the magic link ID, which can be used to check if the magic link has been activate or not, using the getMagicLinkStatus() method.

interface PassageMagicLinkRequest {
    id: string;
}

.newLoginMagicLink(identifier: string)

Creates and send a magic link to login the user. The user will receive an email or text to complete the login.

Parameters

identifier: string - email or phone number, depending on your app settings

Returns

Promise<PassageMagicLinkRequest>

Returns a promise that resolves to a PassageMagicLinkRequest. This type include the magic link ID, which can be used to check if the magic link has been activate or not, using the getMagicLinkStatus() method.

interface PassageMagicLinkRequest {
    id: string;
}

.magicLinkActivate(userMagicLink: string)

Completes a magic link login workflow by activating the magic link. The magic link is in the psg_magic_link query parameter when a user clicks the link in their email or text.

Parameters

userMagicLink: string - full magic link that starts with "ml" (sent via email or text to the user)

Returns

Promise<AuthResult>

This method returns a Promise that resolves with an AuthResult object. The AuthResult object contains an authentication token (JWT) and redirect URL. The auth token should be used on all subsequent authenticated requests to the app. The redirect URL specifies the route that users should be redirected to after completed registration or login

interface AuthResult {
  redirect_url: string;
  auth_token: string;
  refresh_token: string; // if refresh tokens are enabled
  refresh_token_expiration: number; // if refresh tokens are enabled
}

.magicLinkActivateWebAuthnNewDevice(userMagicLink: string)

Completes a magic link login workflow AND add the current device as a new WebAuthn device. The magic link is in the psg_magic_link query parameter when a user clicks the link in their email or text. This should only be used if WebAuthn is supported by the device and browser context.

Parameters

userMagicLink: string - full magic link that starts with "ml" (sent via email or text to the user)

Returns

Promise<AuthResult>

This method returns a Promise that resolves with an AuthResult object. The AuthResult object contains an authentication token (JWT) and redirect URL. The auth token should be used on all subsequent authenticated requests to the app. The redirect URL specifies the route that users should be redirected to after completed registration or login

interface AuthResult {
  redirect_url: string;
  auth_token: string;
}

.getMagicLinkStatus(id: string)

Checks the status of a magic link to see if it has been activated.

Parameters

id: string - ID of the magic link (from response body of login or register with magic link)

Returns

Promise<AuthResult>

This method returns a Promise that resolves with an AuthResult object. The AuthResult object contains an authentication token (JWT) and redirect URL. The auth token should be used on all subsequent authenticated requests to the app. The redirect URL specifies the route that users should be redirected to after completed registration or login

interface AuthResult {
  redirect_url: string;
  auth_token: string;
  refresh_token: string; // if refresh tokens are enabled
  refresh_token_expiration: number; // if refresh tokens are enabled
}

If the magic link ID is invalid or has not been activated, this method will throw a PassageError.