Search…
⌃K
Links

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 or magic links, depending on their device. It also include 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
Returns
appInfo: PassageAppInfo
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
Returns
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.
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
Returns
identifier: string - email or phone number, depending on your app settings
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
Returns
identifier: string - email or phone number, depending on your app settings
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
Return
None. app_id is passed to the constructor.
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
Returns
identifier: string - email or phone number, depending on your app settings
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
Returns
data: createUserPayload - identifier and optional metadata fields for the user
interface CreateUserPayload {
identifier: string;
user_metadata?: object;
}
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;
}
.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
Returns
identifier: string - email or phone number, depending on your app settings
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
Returns
identifier: string - email or phone number, depending on your app settings
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
Returns
userMagicLink: string - full magic link that starts with "ml" (sent via email or text to the user)
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
Returns
userMagicLink: string - full magic link that starts with "ml" (sent via email or text to the user)
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
Returns
id: string - ID of the magic link (from response body of login or register with magic link)
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.