Passkeys

In addition to the reference documentation below, check out our end-to-end guide on how to implement passkeys in web apps using Authsignal.

Creating a passkey

Creating a passkey must be authorized by presenting a challenge with an existing method or tracking an action to obtain a short-lived token.

const response = await authsignal.passkey.signUp({
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
  displayName: "Jane Smith",
});

Parameters

string

A short-lived token obtained by tracking an action.

string

The primary user identifier associated with the passkey, e.g. the user’s email address.

string

An optional secondary user identifier which the browser may display in place of or alongside the username, e.g. the user’s full name.

'platform' | 'cross-platform' | null

The preferred authenticator type. Defaults to platform, which targets the device’s built-in authenticator (e.g. Touch ID or Windows Hello). Set to cross-platform to target a roaming authenticator such as a security key, or null to let the user choose.

string[]

An array of WebAuthn credential hints which guide the browser’s UI, e.g. ["client-device"], ["security-key"], or ["hybrid"].

boolean

Whether to use the automatic passkey upgrade flow. If true, the user’s password manager will be prompted to automatically create a passkey after successful authentication via password autofill.

boolean

Whether to use cookies to bind the session to the browser. Defaults to false. Requires a custom API domain on the same parent domain as your site.

boolean

Whether to keep the browser’s credential manager in sync with the credentials stored by Authsignal. Defaults to true. See Credential syncing for more details.

Response

AuthsignalResponse<SignUpResponse>

Show properties

SignUpResponse

Show properties

string

A new token which can optionally be used to bind another authenticator for the user.

object

Only present on first time verification e.g. enrollment.

Show properties

string

required

The ID of the Authsignal user authenticator.

required

string

required

The date and time the authenticator was created in ISO 8601 format.

string

required

The date and time the authenticator was first verified in ISO 8601 format.

string

The date and time the authenticator was last verified in ISO 8601 format.

boolean

required

Whether the authenticator is the default authenticator for the user.

string

The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.

string

The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.

SMS | WHATSAPP

The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.

string

Only present for passkey authenticators.

Show properties

string

required

The ID of the passkey credential.

string

required

The device ID of the passkey credential.

string

The name of the passkey credential.

string

The AAGUID of the passkey credential.

boolean

required

Whether the passkey credential is backed up.

'singleDevice' | 'multiDevice'

The device type of the passkey credential.

object

The parsed user agent of the passkey credential.

Show properties

string

required

The user agent of the passkey credential.

object

The browser of the passkey credential.

Show properties

string

The name of the browser.

string

The version of the browser.

string

The major version of the browser.

object

The device of the passkey credential.

Show properties

string

The model of the device.

string

The type of the device.

string

The vendor of the device.

object

The engine of the passkey credential.

Show properties

string

The name of the engine.

string

The version of the engine.

object

The OS of the passkey credential.

Show properties

string

The name of the OS.

string

The version of the OS.

object

The CPU of the passkey credential.

Show properties

string

The architecture of the CPU.

string

required

The date and time the passkey credential was verified in ISO 8601 format.

'platform' | 'cross-platform'

The authenticator attachment of the passkey credential.

string

The AAGUID mapping of the passkey credential.

Show properties

string

required

The name of the AAGUID mapping.

string

The SVG icon of the AAGUID mapping in light mode.

string

The SVG icon of the AAGUID mapping in dark mode.

RegistrationResponseJSON

The raw WebAuthn registration response returned by the browser. Most apps can ignore this.

string

See the Error handling section for more details.

string

Automatic passkey upgrades

Automatic passkey upgrades are supported in Safari 18+ on macOS, all browsers on iOS 18+, Chrome 136+ on desktop, and Chrome 142+ on Android.

With passkey upgrades, your app can prompt your user’s password manager to automatically create a passkey. This works provided the user has a password saved for your app in their password manager and has recently authenticated with it. To enable this, you must set the useAutoRegister parameter to true when calling signUp.

const response = await authsignal.passkey.signUp({
  token: "eyJhbGciOiJ...",
  username: "jane.smith@authsignal.com",
  displayName: "Jane Smith",
  useAutoRegister: true,
});

Example usage

async function onSubmit(formData) {
  // Validate user on BE and return a token from `track`

  // If valid user, attempt to automatically create a passkey
  try {
    const response = await authsignal.passkey.signUp({
      token: "eyJhbGciOiJ...", // Token from `track`
      username: "jane.smith@authsignal.com",
      displayName: "Jane Smith",
      useAutoRegister: true,
    });
  } catch (error) {
    // Failed to automatically create a passkey
    console.error(error);
  }

  // Continue with post-sign-in flow
  window.location.href = "/dashboard";
}

Using a passkey

Calling signIn will present the passkey sign-in prompt. If the user successfully authenticates with their passkey, send the result token to your server to validate the challenge.

const response = await authsignal.passkey.signIn({ action: "signInWithPasskey" });

if (response.data?.token) {
  // Send the response token to your server to validate the result of the challenge
}

Check out our best practice guide for passkeys on web browsers for tips on how to implement an optimal passkey UX and avoid leading users into dead ends.

Parameters

string

A string which determines how the action associated with the passkey sign-in attempt will be named in the Authsignal Portal. Values are validated with the following regex: ^[a-zA-Z0-9_-]{(1, 64)}$. Cannot be combined with token.

string

A short-lived token obtained by tracking an action. Use this to authorize the sign-in attempt instead of action. Cannot be combined with action or autofill.

boolean

Whether to use passkey autofill (browser conditional UI). Defaults to false. Cannot be combined with token or preferImmediatelyAvailableCredentials.

function

A callback invoked after the user selects a passkey and the browser ceremony completes, just before the result is verified with the Authsignal API. Useful for showing a loading state.

boolean

Whether to use immediate mediation UI mode, which only prompts the user if a passkey is immediately available on the device. Defaults to false. See Immediately available credentials for more details.

boolean

Whether to use cookies to bind the session to the browser. Defaults to false. Requires a custom API domain on the same parent domain as your site.

boolean

Whether to keep the browser’s credential manager in sync with the credentials stored by Authsignal. Defaults to true. See Credential syncing for more details.

Response

AuthsignalResponse<SignInResponse>

Show properties

SignInResponse

Show properties

boolean

True if the passkey sign-in attempt was successful.

string

A new token which can be used to validate the challenge on your server or optionally to bind another authenticator for the user.

string

The ID of the Authsignal user if the sign-in attempt was successful.

string

The ID of the Authsignal user authenticator if the sign-in attempt was successful.

string

The username associated with the passkey if the sign-in attempt was successful.

string

The display name associated with the passkey if the sign-in attempt was successful.

AuthenticationResponseJSON

The raw WebAuthn authentication response returned by the browser. Most apps can ignore this.

string

See the Error handling section for more details.

string

Using passkey autofill

This feature requires rendering a text input with the attribute autocomplete="username webauthn":

<input type="text" id="username" autocomplete="username webauthn" />

It can also be added to a password input:

<input type="password" id="password" autocomplete="current-password webauthn" />

The webauthn value must be the last value in the autocomplete attribute, otherwise the browser will not autofill the passkey.

Then when the page loads you should initialize the input for passkey autofill by running the following code.

authsignal.passkey
  .signIn({
    action: "signInWithPasskeyAutofill",
    autofill: true,
  })
  .then((response) => {
    if (response.data?.token) {
      // The user has focused your text input and authenticated with an existing passkey
      // Send the response token to your server to validate the result of the challenge
    }
  });

Immediately available credentials

Setting preferImmediatelyAvailableCredentials to true uses the browser’s immediate mediation UI mode. The passkey prompt is only shown if a credential is immediately available on the device, otherwise the call returns without interrupting the user. This is useful for surfacing a passkey prompt at a sign-in moment, such as when the user clicks a sign-in button, without showing an error to users who don’t have a passkey.

const response = await authsignal.passkey.signIn({
  action: "signInWithPasskey",
  preferImmediatelyAvailableCredentials: true,
});

if (response.errorCode === "credential_not_found") {
  // No passkey was immediately available, fall back to another method
} else if (response.data?.token) {
  // Send the response token to your server to validate the result of the challenge
}

Immediate mediation UI mode is only supported in browsers that implement the WebAuthn getClientCapabilities and immediate get APIs. When unsupported, the call returns the immediate_mediation_not_supported error code. It also cannot be combined with autofill.

Credential syncing

A common source of passkey friction is stale credentials: a passkey is deleted on the server but still appears in the user’s browser or password manager, so they select it and hit a dead end. To prevent this, the SDK uses the WebAuthn Signal API to keep the browser’s credential manager in sync with the passkeys stored by Authsignal. This happens automatically while syncCredentials is true (the default), so there’s no separate method to call:

After a successful signUp or signIn, the SDK calls signalAllAcceptedCredentials with the full set of the user’s valid credentials. The browser removes any passkeys for your app that are no longer on this list.
When signIn fails because the presented passkey is no longer recognized by the server (the unknown_credential error code), the SDK calls signalUnknownCredential so the browser removes that specific passkey.

Set syncCredentials to false on signUp or signIn to opt out.

The Signal API is only available in supporting browsers. Where it isn’t supported, syncing is silently skipped and sign-in is unaffected.

Passkey error handling

When any of the underlying native browser WebAuthn APIs fail, the SDK will throw a WebAuthnError. Most of these errors are benign and can be safely ignored. However, if you wish to handle them, you can do so by catching the error in a try/catch block. Common errors you will encounter during passkey authentication are:

ERROR_CEREMONY_ABORTED - The user cancelled the passkey ceremony. We recommend ignoring this error as it’s a normal part of the user experience.
ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED - The user already has a passkey registered for this authenticator (exclusive to signUp). For example, the user is trying to create an iCloud Keychain passkey but already has one registered in iCloud Keychain.

During development, you may also encounter ERROR_INVALID_RP_ID which occurs when the relying party ID is invalid for the domain.

import { WebAuthnError } from "@authsignal/browser";

try {
  const response = await authsignal.passkey.signUp({
    token: "eyJhbGciOiJ...",
    username: "jane.smith@authsignal.com",
    displayName: "Jane Smith",
  });
} catch (error) {
  if (error instanceof WebAuthnError) {
    if (error.code === "ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED") {
      // The user already has a passkey registered for this device
      // You can choose to handle this however you see fit
    }
  }
}

Server

Client

Call Connect

Creating a passkey

Parameters

Response

Automatic passkey upgrades

Example usage

Using a passkey

Parameters

Response

Using passkey autofill

Immediately available credentials

Credential syncing

Passkey error handling

​Creating a passkey

​Parameters

​Response

​Automatic passkey upgrades

​Example usage

​Using a passkey

​Parameters

​Response

​Using passkey autofill

​Immediately available credentials

​Credential syncing

​Passkey error handling

Creating a passkey

Parameters

Response

Automatic passkey upgrades

Example usage

Using a passkey

Parameters

Response

Using passkey autofill

Immediately available credentials

Credential syncing

Passkey error handling