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:
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.
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.
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.
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
interfaceAuthResult { 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.
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
interfaceAuthResult { 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.
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.
interfacePassageAppInfo { 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).
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.
interfacePassageUser { 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).
data: createUserPayload - identifier and optional metadata fields for the user
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.
Creates and send a magic link to register the user. The user will receive an email or text to complete the registration.
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.
interfacePassageMagicLinkRequest { 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.
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.
interfacePassageMagicLinkRequest { 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.
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
interfaceAuthResult { redirect_url:string; auth_token:string; refresh_token:string; // if refresh tokens are enabled refresh_token_expiration:number; // if refresh tokens are enabled}
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.
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
Checks the status of a magic link to see if it has been activated.
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
interfaceAuthResult { 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.