About

Passage by 1Password unlocks the passwordless future with a simpler, more secure passkey authentication experience. Passage handles the complexities of the WebAuthn API, and allows you to implement passkeys with ease.

Use Passkey Flex to add passkeys to an existing authentication experience.

Use Passkey Complete as a standalone passwordless auth solution.

Use Passkey Ready to determine if your users are ready for passkeys.

In passage-js

Passage-JS provides a convenient JavaScript interface to handling all client-side operations for user authentication and management with Passkey Complete. If you're looking for a pre-built UI that handles everything for you elegantly check out our UI library passage-elements or passage-react.

What's Included?

🙆 Getting and editing information about the currently authenticated user.

🤝 Managing the session of the current user.

🔒 Full passkey authentication.

✨ Magic Link and One-Time Passcodes over email or SMS.

👥 Authentication with Social providers.

🪙 Custom token management.

| Product | Compatible | | --- | --- | | Passkey Flex | ✖️ For Passkey Flex, check out passage-flex-js | Passkey Complete | ✅ | Passkey Ready | ✖️ For Passkey Ready, check out Authentikit

Getting Started

Check Prerequisites

Install

npm i @passageidentity/passage-js

Import

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

Initialize

const passage = new Passage('YOUR_PASSAGE_APP_ID');

Go Passwordless

Find aditional customization options and more implementation guidance on our Passkey JS Documentation page.

Support & Feedback

We are here to help! Find additional docs, the best ways to get in touch with our team, and more within our support resources.

API Reference

Classes

Passage

The Passage class used to perform register and login operations. The only parameter is the app handle for the application.

Example

import Passage from '@passageidentity/passage-js';
const passage = new Passage(app_id);

Constructors

new Passage()

new Passage(appID, config?): Passage

Constructor configuring the Passage class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | appID | string | the App's corresponding AppID | | config? | PassageConfig | An optional parameter to pass in configurable properties. The tokenStore property is an object that implements ReadOnlyTokenStore or TokenStore to manage retrieval and storage of tokens. If no tokenStore is provided by default Passage will store tokens in a combination of localstorage and cookies. |

Returns

Passage

Properties

app

app: PassageApp

PassageApp class contains functions that operate on the Passage app level.

currentUser

currentUser: PassageCurrentUser

The PassageCurrentUser class contains functions to get information about the currently authenticated user.

magicLink

magicLink: PassageMagicLink

PassageMagicLink class contains functions that use magic links for authentication, identitfy verification, and handling identifier changes.

oneTimePasscode

oneTimePasscode: PassageOneTimePasscode

PassageOneTimePasscode class contains functions that use one-time passcodes for authentication.

passkey

passkey: PassagePasskey

PassagePasskey class contains functions that use passkeys for authentication and utilities to help with passkey UX decisions.

session

session: PassageSession

The PassageSession class used to manage Passage sessions using refresh tokens.

social

social: PassageSocial

PassageSocial class contains functions that use social providers for authentication.

PassageApp

PassageApp class contains functions that operate on the Passage app level.

Extends

• PassageBase<AppsApi>

Constructors

new PassageApp()

new PassageApp(instanceConfig): PassageApp

Constructor configuring the App class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance |

Returns

PassageApp

Overrides

PassageBase<AppsApi>.constructor

Methods

createUser()

createUser(identifier, userMetadata?): Promise<User>

createUser creates a user in a 'pending' state.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | the email or phone number of the user | | userMetadata? | Metadata | optional metadata to associate with the user |

Returns

Promise<User>

info()

info(): Promise<App>

Get information about an app.

Returns

Promise<App>

a data object containing app information and the authentication policy

Example

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

const passage = new Passage(appId);

await passage.app.info()
 .then(data => {
     // look at information regarding a particular app
 }).catch(e => console.log(e));

userExists()

userExists(identifier): Promise<User>

Look-up a user and return the user properties if the user exists

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | email address / phone for user |

Returns

Promise<User>

PassageCurrentUser

The PassageCurrentUser class contains functions to get information about the currently authenticated user.

Extends

• PassageBaseAuthenticated<CurrentuserApi>

Constructors

new PassageCurrentUser()

new PassageCurrentUser(instanceConfig, session): PassageCurrentUser

constructor for the CurrentUser class.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance | | session | PassageSession | - |

Returns

PassageCurrentUser

Overrides

PassageBaseAuthenticated<CurrentuserApi>.constructor

Methods

addPasskey()

addPasskey(options?): Promise<Credential>

addPasskey register a new passkey for the current user.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | options? | PasskeyCreationOptions | Optional configuration for passkey creation |

Returns

Promise<Credential>

the new passkey regsitered for the current user.

changeEmail()

changeEmail(newEmail, language?): Promise<MagicLink>

changeEmail initiates an email change for the authenticated user. An email change requires verification, so an email will be sent to the user which they must verify before the email change takes effect.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | newEmail | string | | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<MagicLink>

the magicLink response on success.

changePhone()

changePhone(newPhone, language?): Promise<MagicLink>

changePhone initiates a phone number change for the authenticated user. An phone number change requires verification, so an SMS with a link will be sent to the user which they must verify before the phone number change takes effect.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | newPhone | string | | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<MagicLink>

the magicLink response on success.

deletePasskey()

deletePasskey(passkey): Promise<boolean>

deletePasskey deletes an existing passkey for the current user.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | passkey | Credential | the passkey to be deleted |

Returns

Promise<boolean>

true if the device has been deleted successfully.

deleteSocialConnection()

deleteSocialConnection(socialConnectionType): Promise<boolean>

deleteSocialConnection deletes an existing social connection for the current user.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | socialConnectionType | SocialConnection | the social connection to be deleted |

Returns

Promise<boolean>

true if the social connection has been deleted successfully.

editPasskey()

editPasskey(passkeyId, friendlyName): Promise<Credential>

editPasskey allows the passkey's friendly name to be changed.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | passkeyId | string | | | friendlyName | string | |

Returns

Promise<Credential>

the edited device after applying the requested device attribute changes.

listSocialConnections()

listSocialConnections(): Promise<UserSocialConnections>

listSocialConnections is used to list the current user's social connections.

Returns

Promise<UserSocialConnections>

the current social connections and their properties.

metadata()

metadata(): Promise<Metadata>

getMetadata returns the metadata for the currently authenticated user.

Returns

Promise<Metadata>

the current Passage user's info, or undefined if the current Passage user's authentication token could not be validated.

passkeys()

passkeys(): Promise<Credential[]>

Get the list of the current users's passkeys.

Returns

Promise<Credential[]>

the array of passkeys.

updateMetadata()

updateMetadata(metadata): Promise<CurrentUser>

updateMetadata updates the metadata for the currentuser. Note that only metadata fields set for the app can be updated.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | metadata | Metadata | |

Returns

Promise<CurrentUser>

the current user with their newly updated metadata field.

userInfo()

userInfo(): Promise<CurrentUser>

userInfo returns the user information for the currently authenticated user. If the user is not authenticated, an error is thrown.

Returns

Promise<CurrentUser>

the current Passage user's info current Passage user's authentication token could not be validated.

PassageMagicLink

PassageMagicLink class contains functions that use magic links for authentication, identitfy verification, and handling identifier changes.

Extends

• PassageBase<MagicLinkApi>

Constructors

new PassageMagicLink()

new PassageMagicLink(instanceConfig): PassageMagicLink

Constructor configuring the PassageMagicLink class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance |

Returns

PassageMagicLink

Overrides

PassageBase<MagicLinkApi>.constructor

Methods

activate()

activate(magicLink): Promise<AuthResult>

Activates a magic link. Handles login, registration, identifier verification, and identifier change magic links. Will throw an error if the magic link is invalid, expired, or has already been activated.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | magicLink | string | The magic link to activate |

Returns

Promise<AuthResult>

login()

login(identifier, language?): Promise<MagicLink>

Creates a new magic link for login. Will throw an error if the user does not exist.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | The Passage User's identifier | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<MagicLink>

MagicLink JSON payload

register()

register(identifier, language?): Promise<MagicLink>

Create a new magic link for registration. Will throw an error if the user has already logged into their account at least once.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | The Passage User's identifier | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<MagicLink>

MagicLink JSON payload

status()

status(id): Promise<AuthResult>

Look up a magic link by ID and check if it has been verified. This function is most commonly used to iteratively check if a user has clicked a magic link to login. Once the link has been verified, Passage will return authentication information via this endpoint. This enables cross-device login. This will throw an error if the magic link is not activated.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | id | string | unique ID for an magic link which is returned by functions that create a magic link |

Returns

Promise<AuthResult>

PassageOneTimePasscode

PassageOneTimePasscode class contains functions that use one-time passcodes for authentication.

Extends

• PassageBase<OTPApi>

Constructors

new PassageOneTimePasscode()

new PassageOneTimePasscode(instanceConfig): PassageOneTimePasscode

Constructor configuring the PassageOneTimePasscode class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance |

Returns

PassageOneTimePasscode

Overrides

PassageBase<OTPApi>.constructor

Methods

activate()

activate(oneTimePasscode, id): Promise<AuthResult>

Activates a one-time passcode. Handles login and registration one-time passcodes. Will throw an error if the one-time passcode is invalid, expired, or has already been activated.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | oneTimePasscode | string | The one-time passcode provided by the user from their email or text message. | | id | string | The id associated with the one-time passcode. |

Returns

Promise<AuthResult>

login()

login(identifier, language?): Promise<OneTimePasscodeResponse>

Create a new one-time passcode for login. Will throw an error if the user does not exist.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | The Passage User's identifier | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<OneTimePasscodeResponse>

One-time passcode object

register()

register(identifier, language?): Promise<OneTimePasscodeResponse>

Create a new one-time passcode for registration. Will throw an error if the user has already logged into their account at least once.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | The Passage User's identifier | | language? | string | the language string for localizing emails, if no lanuage or an invalid language is provided the application default lanuage will be used |

Returns

Promise<OneTimePasscodeResponse>

One-time passcode object

PassagePasskey

PassagePasskey class contains functions that use passkeys for authentication and utilities to help with passkey UX decisions.

Constructors

new PassagePasskey()

new PassagePasskey(instanceConfig, app): PassagePasskey

Constructor configuring the Passkey class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance | | app | PassageApp | - |

Returns

PassagePasskey

Methods

checkPasskeyOrigin()

checkPasskeyOrigin(): Promise<boolean>

Checks if an application's auth origin matches the current origin on an end user's browser. If this function returns false, passkeys will not work properly on this domain.

Returns

Promise<boolean>

createCredentialAvailable()

createCredentialAvailable(): Promise<ICreateCredentialFeatures>

Uses information about the user's current browser to determine what features are availble for creating credentials via WebAuthn. NOTE: Do not call this from an event handler where navigator.get or navigator.create is invoked or it will break the required user gesture on iOS web browsers.

Returns

Promise<ICreateCredentialFeatures>

The set of features supported by the browser.

getCredentialAvailable()

getCredentialAvailable(): Promise<IGetCredentialFeatures>

Uses information about the user's current browser to determine what features are availble for getting credentials via WebAuthn. NOTE: Do not call this from an event handler where navigator.get or navigator.create is invoked or it will break the required user gesture on iOS web browsers.

Returns

Promise<IGetCredentialFeatures>

The set of features supported by the browser.

hasLocalPasskey()

hasLocalPasskey(userId): boolean

Checks to see if the user has any platform passkeys. This happens by checking to see if we have the userID and an associated passkey credential stored in localStorage via the key psg_cred_obj.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | userId | string | the Passage User's userID |

Returns

boolean

returns true if psg_cred_obj exists in localstorage, false if not

login()

login(identifier?, options?): Promise<AuthResult>

Logs in an existing user with a passkey. Will throw an error if the user does not exist, has no passkeys, or if the operation is cancelled with an abort signal. If no identifier is provided, the user will be prompted to select an identifier, formally known as WebAuthn discoverable credentials. If implementing passkey autocomplete, formally known as WebAuthn conditional mediation, no identifier should be provided and the isConditionalMediation option should be set to true.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier? | string | | | options? | PasskeyLoginOptions | |

Returns

Promise<AuthResult>

The authentication token, redirect URL, and refresh token, if configured for the application.

register()

register(identifier, options?): Promise<AuthResult>

Registers a new user with a passkey. Will throw an error if the user has already logged into their account at lesst once.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | identifier | string | | | options? | PasskeyCreationOptions | |

Returns

Promise<AuthResult>

The authentication token, redirect URL, and refresh token, if configured for the application.

PassageSession

The PassageSession class used to manage Passage sessions using refresh tokens.

Extends

• PassageBase<TokensApi>

Constructors

new PassageSession()

new PassageSession(instanceConfig): PassageSession

Constructor configuring the PassageOneTimePasscode class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance |

Returns

PassageSession

Overrides

PassageBase<TokensApi>.constructor

Methods

authGuard()

authGuard(): Promise<boolean>

authGuard checks if the current user has a JWT that is valid and potentially verifiable. IMPORTANT: this is not verifying the JWT, it is only checking if the JWT is formatted properly.

Returns

Promise<boolean>

true if the user has a valid (but unverified) JWT, false if not.

getAuthToken()

getAuthToken(): Promise<string>

getAuthToken gets the current authToken for the currently authenticated user.

Returns

Promise<string>

returns the user's authToken if it exists or fetches a new one with a refresh token if it exists

refresh()

refresh(): Promise<AuthResult>

refresh gets and saves a new authToken for the currently authenticated user using their refresh token

Returns

Promise<AuthResult>

returns the user's authToken if successful

signOut()

signOut(): Promise<boolean>

Sign out a user by deleting their AuthToken from local storage and revoking their refresh token.

Returns

Promise<boolean>

true if the device has been deleted successfully.

PassageSocial

PassageSocial class contains functions that use social providers for authentication.

Extends

• PassageBase<OAuth2Api>

Constructors

new PassageSocial()

new PassageSocial(instanceConfig): PassageSocial

Constructor configuring the PassageSocial class' attributes

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | instanceConfig | PassageInstanceConfig | the config of the current Passage instance |

Returns

PassageSocial

Overrides

PassageBase<OAuth2Api>.constructor

Methods

authorize()

authorize(connection): Promise<void>

Initiates authorization via a supported third-party social provider. This must be run from a secure context (HTTPS or localhost).

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | connection | SocialConnection | The social connection to use for login. |

Returns

Promise<void>

finish()

finish(code): Promise<AuthResult>

Finishes a social login by exchanging the social login provider code for Passage tokens.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | code | string | The code returned from the social login provider |

Returns

Promise<AuthResult>

PassageTokenStore

PassageTokenStore class provides the Passage default token storage mechanism. The auth token is stored in localStorage and cookies. The refresh token is stored in localStorage only.

Extends

• TokenStore

Constructors

new PassageTokenStore()

new PassageTokenStore(): PassageTokenStore

Returns

PassageTokenStore

Inherited from

TokenStore.constructor

Methods

clearTokens()

clearTokens(): Promise<void>

Clears the auth token from localstorage and cookies and refresh token from localstorage

Returns

Promise<void>

Overrides

TokenStore.clearTokens

getAuthToken()

getAuthToken(): Promise<string>

Gets the current auth token

Returns

Promise<string>

The current auth token

Overrides

TokenStore.getAuthToken

getRefreshToken()

getRefreshToken(): Promise<undefined | string>

Gets the current refresh token

Returns

Promise<undefined | string>

The current refresh token

Overrides

TokenStore.getRefreshToken

setTokens()

setTokens(authResult): Promise<void>

Sets the auth token and refresh token, if used

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | authResult | AuthResult | |

Returns

Promise<void>

Overrides

TokenStore.setTokens

abstract ReadOnlyTokenStore

Base class for implementing read-only token stores. getAuthToken() is the only required function to implement. If a Passage object is built with a read-only token store it will not handle any token storage.

Extended by

• TokenStore

Constructors

new ReadOnlyTokenStore()

new ReadOnlyTokenStore(): ReadOnlyTokenStore

Returns

ReadOnlyTokenStore

Methods

getAuthToken()

abstract getAuthToken(): Promise<string>

This method returns a token to be used for authenticated operations on the User class.

Returns

Promise<string>

Passage-issued JWT

getRefreshToken()

getRefreshToken(): Promise<undefined | string>

This method retrieves a Passage refresh token from storage for use with the Session class for refreshing Passage sessions. If this method returns undefined then Session will not handle any refresh token logic.

Returns

Promise<undefined | string>

refresh token, or undefined if not using refresh tokens.

abstract TokenStore

Base class for implementing full read-write token stores.

Extends

• ReadOnlyTokenStore

Extended by

• PassageTokenStore

Constructors

new TokenStore()

new TokenStore(): TokenStore

Returns

TokenStore

Inherited from

ReadOnlyTokenStore.constructor

Methods

clearTokens()

clearTokens(): Promise<void>

This method is responsible for clearing tokens from storage when a sign-out operation is executed on the Session class.

Returns

Promise<void>

getAuthToken()

abstract getAuthToken(): Promise<string>

This method returns a token to be used for authenticated operations on the User class.

Returns

Promise<string>

Passage-issued JWT

Inherited from

ReadOnlyTokenStore.getAuthToken

getRefreshToken()

getRefreshToken(): Promise<undefined | string>

This method retrieves a Passage refresh token from storage for use with the Session class for refreshing Passage sessions. If this method returns undefined then Session will not handle any refresh token logic.

Returns

Promise<undefined | string>

refresh token, or undefined if not using refresh tokens.

Inherited from

ReadOnlyTokenStore.getRefreshToken

setTokens()

abstract setTokens(authResult): Promise<void>

This method is responsible for hanlding the storage of Passage-issued JWTs and refresh tokens.

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | authResult | AuthResult | The authResult object returned from Passage Login, Register, Magic Link, and token refresh operations. |

Returns

Promise<void>

Interfaces

Metadata

Indexable

[key: string]: boolean | string | number

PassageConfig

Properties

| Property | Type | Description | | ------ | ------ | ------ | | tokenStore? | ReadOnlyTokenStore | TokenStore | A custom TokenStore implementation that handles custom management of tokens |

PasskeyLoginOptions

Properties

| Property | Type | | ------ | ------ | | abortSignal? | AbortSignal | | isConditionalMediation? | boolean |

Enumerations

Identifier

Enumeration Members

| Enumeration Member | Value | | ------ | ------ | | both | "both" | | email | "email" | | phone | "phone" |

RequiredIdentifier

Enumeration Members

| Enumeration Member | Value | | ------ | ------ | | Both | "both" | | Either | "either" | | Email | "email" | | Phone | "phone" |

SocialConnection

Enumeration Members

| Enumeration Member | Value | | ------ | ------ | | Apple | "apple" | | Github | "github" | | Google | "google" |

UserMetadataType

Enumeration Members

| Enumeration Member | Value | | ------ | ------ | | BOOLEAN | "boolean" | | DATE | "date" | | EMAIL | "email" | | INTEGER | "integer" | | PHONE | "phone" | | STRING | "string" |

Functions

isFullTokenStore()

isFullTokenStore(store): store is TokenStore

Parameters

| Parameter | Type | | ------ | ------ | | store | ReadOnlyTokenStore | TokenStore |

Returns

store is TokenStore

Type Aliases

OneTimePasscode

OneTimePasscode: OneTimePasscodeResponse

PassageAppInfo

PassageAppInfo: App

Passkey

Passkey: Credential

PublicUserInfo

PublicUserInfo: User

UserSocialConnection

UserSocialConnection: AppleSocialConnection | GithubSocialConnection | GoogleSocialConnection