How the pre-built UI should launch: popup will cause it to open in a overlay, whilst
redirect will trigger a full page redirect. If no value is supplied, mode defaults to
redirect.
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.
A formatted error code which may additionally be present if the SDK call encountered an error.
Possible values are: token_not_set, invalid_token, expired_token or user_canceled.
Automatic passkey upgrades are currently only supported by Safari on macOS and iOS, and Chrome on
desktop.
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.
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@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";}
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.
Copy
Ask AI
const response = await authsignal.passkey.signIn({ action: "signInWithPasskey" });if (response.token) { // Send token to your server to validate the result}
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)}$.
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.
Copy
Ask AI
authsignal.passkey .signIn({ action: "signInWithPasskeyAutofill", autofill: true, }) .then((token) => { if (token) { // The user has focused your text input and authenticated with an existing passkey // Send the token to your server to validate the result of the challenge } });
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.
Copy
Ask AI
import { WebAuthnError } from "@authsignal/browser";try { const response = await authsignal.passkey.signUp({ token: "eyJhbGciOiJ...", username: "jane@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 authenticator // You can choose to handle this however you see fit } }}
Start enrollment for a new email OTP authenticator by sending the user an email containing an OTP code.This method is typically used when you’ve not yet verified the user’s email address.
If you’ve already verified a user’s email address independently of Authsignal, you can
alternatively use a Server SDK to enroll the user
programmatically.
Start re-authentication for an existing email OTP authenticator by sending the user an email containing an OTP code.This method is typically used when you’ve already verified the user’s email address.
Start enrollment for a new email magic link authenticator by sending the user an email containing a verification link.This method is typically used when you’ve not yet verified the user’s email address.
If you’ve already verified a user’s email address independently of Authsignal, you can
alternatively use a Server SDK to enroll the user
programmatically.
Start re-authentication for an existing email magic link authenticator by sending the user an email containing a verification link.This method is typically used when you’ve already verified the user’s email address.
Start enrollment for a new SMS OTP authenticator by sending the user an SMS containing an OTP code.This method is typically used when you’ve not yet verified the user’s phone number.
If you’ve already verified a user’s phone number independently of Authsignal, you can
alternatively use a Server SDK to enroll the user
programmatically.
Start re-authentication for an existing SMS authenticator by sending the user an SMS containing an OTP code.This method is typically used when you’ve already verified the user’s phone number.
A JSON object which can include any key/value pairs. Can be used to provide additional context to the challenge which can be reviewed on the user’s mobile device.
The interval in milliseconds at which the challenge should be refreshed. Defaults to 540000 (9 minutes). This should be set to a value lower than your token’s expiry time to allow a tolerance for the challenge to be completed.
Whether to poll for the challenge result using RESTful API endpoints. Should only be used if you are unable to use WebSocket connections.Defaults to false and uses WebSockets.
When using web SDK methods for email OTP, SMS OTP or authenticator app (TOTP) you must first track an action using a Server SDK or the Server API to generate a time-limited token (valid for 10 minutes by default).
For enrollment flows, you must also specify the scope add:authenticators when tracking the
action if the user already has an existing authenticator. For more detail refer to our guide on
how to ensure a strong binding when adding
authenticators.
Then you can use the SDK’s setToken method.
You must use the same token for the initial enroll/challenge call and the subsequent verify call.
Copy
Ask AI
authsignal.setToken("eyJhbGciOiJ...");// Send the user an email OTP code// You can call this multiple times via a 'resend' buttonawait authsignal.email.challenge();// Verify the inputted code matches the original codeconst response = await authsignal.email.verify({ code: "123456" });