Passkey Flex JavaScript SDK

Install

Via NPM

Install the Passkey Flex JavaScript npm package (opens in a new tab).

npm install @passageidentity/passage-flex-js

Via CDN

https://cdn.passage.id/passage-flex-js.js

Import

import { PassageFlex } from 'passage-flex-js';

Initialize

Initialize a Passkey Flex instance using your app ID found in Passage Console.

App.js

const passageFlex = new PassageFlex(appID);

Core functions

passkey.register()

Parameters

Property	Data Type	Description
`transactionID`	`string`	Retrieve from Passkey Flex API. Learn more here.
`options?`	`IPasskeyCreationOptions:` `{` `authenticatorAttachment?: AuthenticatorAttachment}`	`authenticatorAttachment` controls what kind of passkey the browser prompts the user to create. `AuthenticatorAttachment` is an enum with the values `Platform`, `CrossPlatform`, or `Any`. The default value is `Platform`.

Returns

Promise<string>

Register the user using a transaction ID retrieved from the Passage API using a Passkey Flex backend SDK. Returns a nonce. You can use the nonce in a backend SDK to verify that Passage has registered the user successfully.

Example

index.html

<input id="register-input" type="email" placeholder="you@example.com" />
<button id="register-button" type="button" onclick="onRegisterPasskeyClick()">Register</button>

App.js

async function onRegisterPasskeyClick() {
    const nonce = await passageFlex.passkey.register(transactionID);
}

passkey.authenticate()

Parameters

Property	Data Type	Description
`options?`	`IPasskeyAuthenticateOptions:` `{` `transactionId?: string,` `isConditionalMediation?: boolean` `}`	`transactionId` is retrieved from the Passkey Flex API. Learn more here. `isConditionalMediation` determines whether passkey autofill should be used. By default this is `false` as passkey autofill only works with discoverable credentials.

Returns

Promise<string>

Authenticate the user. Returns a nonce.

There are three ways to authenticate users with passkeys. Review the Authenticate Implementation Guide to learn more.

With an external identifier

Authenticate the user with a transaction ID retrieved from the Passage API using a Passkey Flex backend SDK. This requires the user to enter an external identifier (email or username) to authenticate.

Example

index.html

<input id="authenticate-input" type="email" placeholder="you@example.com" />
<button id="authenticate-button" type="button" onclick="onAuthenticatePasskeyClick()">Log in</button>

App.js

async function onAuthenticatePasskeyClick() {
    const nonce = await passageFlex.passkey.authenticate({ transactionID });
}

Without an external identifier

Authenticate the user using discoverable credentials. The user isn't required to type in any identifier. A typical UX for this flow is "one-click" authentication using a button. The user will be provided all passkey options for the app on the device.

Example

index.html

<button id="authenticate-button" type="button" onclick="onAuthenticatePasskeyClick()">Log in</button>

App.js

async function onAuthenticatePasskeyClick() {
    const nonce = await passageFlex.passkey.authenticate();
}

Passkey autofill

Authenticate the user using passkey autofill (also known as conditional mediation). This requires the user to have a discoverable credential and a browser that supports passkey autofill. The user will click into an identifier input field and the browser will display available passkeys in an autofill dropdown. The order of the tokens in the autofill HTML attribute must be username webauthn.

Example

index.html

<input autocomplete="username webauthn" id="authenticate-input" type="email" placeholder="you@example.com" />
<button id="authenticate-button" type="button" onclick="onAuthenticatePasskeyClick()">Log in</button>

App.js

// A request to authenticate with passkey autofill should be made on page load.
async function onPageLoad() {
    const nonce = await passageFlex.passkey.authenticate({ isConditionalMediation: true });
}
 
// This is not necessary for passkey autofill to work,
// but it's good practice to make sure users can still authenticate if passkey autofill is not available.
async function onAuthenticatePasskeyClick() {
    const nonce = await passageFlex.passkey.authenticate({ transactionID });
}

Helper functions

Helpful utility functions to check for Webauthn capabilities in the user's current browser. For example, these functions can be used to check for Webauthn capabilities before displaying the option to the user.

passkey.canAuthenticateWithPasskey()

Returns

Promise<boolean>

A promise that resolves true if the current browser supports passkey authentication, false otherwise.

Example

App.js

const isPasskeyAuthenticationAvailable = await passageFlex.passkey.canAuthenticateWithPasskey();
 
if (isPasskeyAuthenticationAvailable) {
    return <button onClick={onAuthenticateWithPasskeyClick}>Log in with passkey</button>;
}

passkey.canRegisterPasskey()

Returns

Promise<boolean>

A promise that resolves true if the current browser supports passkey creation, false otherwise.

Example

App.js

const isPasskeyRegistrationAvailable = await passageFlex.passkey.canRegisterPasskey();
 
if (isPasskeyRegistrationAvailable) {
    return <button onClick={onRegisterWithPasskeyClick}>Log in with passkey</button>;
}

passkey.canUseConditionalMediation()

Returns

Promise<boolean>

A promise that resolves true if the current browser supports passkey autofill, false otherwise.

Example

App.js

const isConditionalMediationAvailable = await passageFlex.passkey.canUseConditionalMediation();
 
if (isConditionalMediationAvailable) {
    return await passageFlex.passkey.authenticate({ isConditionalMediation: true });
}