@passageidentity/passage-flex-js

Passage Passkey Flex is currently in Beta!

Passage Passkey Flex is under active development and may see breaking changes before the first major version release. Please continue to check [our documentation](https://docs-v2.passage.id/) for updates regularly!

PassageFlex JS

Passkey Flex provides passkey authentication support to existing authentication systems. It handles the hard parts of incorporating the WebAuthn API and provides a simple, clean solution to take your authentication to the next level.

Use the passage-flex-js JS SDK to implement Passkey Flex in your web application to use passkeys to register, authenticate, or as added security on secure user actions.

For full documentation, including setting up a backend SDK, visit the Passkey Flex documentation here.

Getting started

Install this package using npm:

npm i --save @passageidentity/passage-flex-js

Import PassageFlex:

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

Initialize a Passage Flex instance using your appId found in Passage Console:

const passageFlex = new PassageFlex(appID);

Core Functions

passkey.register(transactionId: string)

Returns

Promise<string>

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

Example

<input id="register-input" type="email" placeholder="[e-mail]" />
<button id="register-button" type="button" onclick="onRegisterPasskeyClick()">Register</button>

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

passkey.authenticate(options?: {transactionId?: string, isConditionalMediation?: boolean})

Returns

Promise<string>

Authenticate the user. Returns a nonce. There are three ways to authenticate users with passkeys:

1. With a unique identifier, eg. a username or email which requires an input and identifier

   Example

   <input id="authenticate-input" type="email" placeholder="[e-mail]" />
   <button id="authenticate-button" type="button" onclick="onAuthenticatePasskeyClick()">
       Log in
   </button>

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

2. Without a unique identifier, eg. a single "Log in" CTA which does not require an input or identifier

   Example

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

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

3. Using Passkey Autofill, eg. a dropdown with available passkeys is displayed to the user on clicking an identifier input

   Example

   <input autocomplete="username webauthn" id="authenticate-input" type="email" placeholder="[e-mail]" />
   <button id="authenticate-button" type="button" onclick="onAuthenticatePasskeyClick()">Log in</button>

   // A request to authenticate with conditional mediation should be made on page load.
   async function onPageLoad() {
       const nonce = await passageFlex.passkey.authenticate({ isConditionalMediation: true });
   }

For more information on authenticating with Passkey Flex using passage-flex-js, see the Passkey Flex Authenticate documentation here.

Helper Functions

PassageFlexJS provides 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

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.

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 conditional mediation (passkey autofill), false otherwise.

Example

const isConditionalMediationAvailable = await passageFlex.passkey.canUseConditionalMediation();

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