The Authsignal Web SDK can be used to:
Launch the pre-built UI to let users set up MFA and complete challenges
Sign up and sign in users using passkeys
Build custom UIs for authenticating with email OTP, SMS OTP, or authenticator app
Installation
npm install @authsignal/browser
This will add our module to your package.json
.
Initialization
Initialize the client with your tenant ID and the API URL for your region.
import { Authsignal } from "@authsignal/browser" ;
const authsignal = new Authsignal ({
tenantId: "YOUR_TENANT_ID" ,
baseUrl: "YOUR_REGION_BASE_URL" ,
});
You can find your tenantId
in the Authsignal Portal .
You must specify the correct baseUrl
for your tenant’s region.
Region API URL US (Oregon) https://api.authsignal.com/v1
AU (Sydney) https://au.api.authsignal.com/v1
EU (Dublin) https://eu.api.authsignal.com/v1
Launching the pre-built UI
The Web SDK can be used to launch the pre-built UI .
authsignal . launch ( url , options );
Parameters
The options used when launching the pre-built UI.
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
.
Any valid CSS value for the width
property.
Whether the popup is closable with the escape key and by clicking the backdrop.
Response
When mode
is set as popup
it returns a Promise<TokenPayload>
that resolves when the popup closes.
The token that can be used to verify the outcome of the user action.
For more information on launching the pre-built UI see our detailed guide .
Passkeys
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@authsignal.com" ,
displayName: "Jane Smith" ,
});
Parameters
The primary user identifier associated with the passkey, e.g. the user’s email address.
An optional secondary user identifier which the browser may display in place of or alongside the
username, e.g. the user’s full name.
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.
Response
response
AuthsignalResponse<SignUpResponse>
An unstructured error description present if the SDK call encountered an error.
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
.
Only present on first time verification e.g. enrollment.
The ID of the Authsignal user authenticator.
verificationMethod
'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PASSKEY' | 'PUSH' | 'SECURITY_KEY' | 'VERIFF' | 'IPROOV' | 'IDVERSE' | 'PALM_BIOMETRICS_BR'
required
The date and time the authenticator was created in ISO 8601 format.
The date and time the authenticator was first verified in ISO 8601 format.
The date and time the authenticator was last verified in ISO 8601 format.
Whether the authenticator is the default authenticator for the user.
The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.
The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
Only present for passkey authenticators.
The ID of the passkey credential.
The device ID of the passkey credential.
The name of the passkey credential.
The AAGUID of the passkey credential.
Whether the passkey credential is backed up.
credentialDeviceType
'singleDevice' | 'multiDevice'
The device type of the passkey credential.
The parsed user agent of the passkey credential.
The user agent of the passkey credential.
The browser of the passkey credential.
The version of the browser.
The major version of the browser.
The device of the passkey credential.
The vendor of the device.
The engine of the passkey credential.
The version of the engine.
The OS of the passkey credential.
The CPU of the passkey credential.
The architecture of the CPU.
The date and time the passkey credential was verified in ISO 8601 format.
authenticatorAttachment
'platform' | 'cross-platform'
The authenticator attachment of the passkey credential.
The AAGUID mapping of the passkey credential.
The name of the AAGUID mapping.
The SVG icon of the AAGUID mapping in light mode.
The SVG icon of the AAGUID mapping in dark mode.
Automatic passkey upgrades
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
.
const response = await authsignal . passkey . signUp ({
token: "eyJhbGciOiJ..." ,
username: "jane@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@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 . token ) {
// Send token to your server to validate the result
}
Parameters
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)}$
.
Response
response
AuthsignalResponse<SignInResponse>
An unstructured error description present if the SDK call encountered an error.
True if the passkey sign-in attempt was successful.
The ID of the Authsignal user if the sign-in attempt was successful.
The ID of the Authsignal user authenticator if the sign-in attempt was successful.
The username associated with the passkey if the sign-in attempt was successful.
The display name associated with the passkey if the sign-in attempt was successful.
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 (( 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
}
});
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@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
}
}
}
Email OTP
All email OTP SDK methods require you to set a token first .
Enroll email
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.
const response = await authsignal . email . enroll ({ email: "jane@authsignal.com" });
Parameters
The user’s email address.
Response
response
AuthsignalResponse<EnrollResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal user.
The ID of the Authsignal user authenticator.
Challenge email
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.
const response = await authsignal . email . challenge ();
Response
response
AuthsignalResponse<ChallengeResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal challenge.
Verify email
Finish enrolling or re-authenticating a new or existing email OTP authenticator by verifying the code submitted by the user.
const response = await authsignal . email . verify ({ code: "123456" });
Parameters
The OTP code inputted by the user.
Response
response
AuthsignalResponse<VerifyResponse>
An unstructured error description present if the SDK call encountered an error.
True if the verification was successful.
Only present on first time verification e.g. enrollment.
The ID of the Authsignal user authenticator.
verificationMethod
'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PASSKEY' | 'PUSH' | 'SECURITY_KEY' | 'VERIFF' | 'IPROOV' | 'IDVERSE' | 'PALM_BIOMETRICS_BR'
required
The date and time the authenticator was created in ISO 8601 format.
The date and time the authenticator was first verified in ISO 8601 format.
The date and time the authenticator was last verified in ISO 8601 format.
Whether the authenticator is the default authenticator for the user.
The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.
The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
Only present for passkey authenticators.
The ID of the passkey credential.
The device ID of the passkey credential.
The name of the passkey credential.
The AAGUID of the passkey credential.
Whether the passkey credential is backed up.
credentialDeviceType
'singleDevice' | 'multiDevice'
The device type of the passkey credential.
The parsed user agent of the passkey credential.
The user agent of the passkey credential.
The browser of the passkey credential.
The version of the browser.
The major version of the browser.
The device of the passkey credential.
The vendor of the device.
The engine of the passkey credential.
The version of the engine.
The OS of the passkey credential.
The CPU of the passkey credential.
The architecture of the CPU.
The date and time the passkey credential was verified in ISO 8601 format.
authenticatorAttachment
'platform' | 'cross-platform'
The authenticator attachment of the passkey credential.
The AAGUID mapping of the passkey credential.
The name of the AAGUID mapping.
The SVG icon of the AAGUID mapping in light mode.
The SVG icon of the AAGUID mapping in dark mode.
A structured code present if the verification failed due to user error. Possible values are:
CODE_INVALID_OR_EXPIRED
or MAX_ATTEMPTS_EXCEEDED
.
Email magic link
All email magic link SDK methods require you to set a token first .
Enroll email magic link
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.
const response = await authsignal . emailML . enroll ({ email: "jane@authsignal.com" });
Parameters
The user’s email address.
Response
response
AuthsignalResponse<EnrollResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal user.
The ID of the Authsignal user authenticator.
Challenge email magic link
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.
const response = await authsignal . emailML . challenge ();
Response
response
AuthsignalResponse<ChallengeResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal challenge.
Check email magic link verification status
Check the verification status of an email magic link authenticator. When the user clicks a valid
magic link, the promise will resolve.
const response = await authsignal . emailML . checkVerificationStatus ();
Response
response
AuthsignalResponse<VerifyResponse>
An unstructured error description present if the SDK call encountered an error.
True if the verification was successful.
Only present on first time verification e.g. enrollment.
The ID of the Authsignal user authenticator.
verificationMethod
'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PASSKEY' | 'PUSH' | 'SECURITY_KEY' | 'VERIFF' | 'IPROOV' | 'IDVERSE' | 'PALM_BIOMETRICS_BR'
required
The date and time the authenticator was created in ISO 8601 format.
The date and time the authenticator was first verified in ISO 8601 format.
The date and time the authenticator was last verified in ISO 8601 format.
Whether the authenticator is the default authenticator for the user.
The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.
The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
Only present for passkey authenticators.
The ID of the passkey credential.
The device ID of the passkey credential.
The name of the passkey credential.
The AAGUID of the passkey credential.
Whether the passkey credential is backed up.
credentialDeviceType
'singleDevice' | 'multiDevice'
The device type of the passkey credential.
The parsed user agent of the passkey credential.
The user agent of the passkey credential.
The browser of the passkey credential.
The version of the browser.
The major version of the browser.
The device of the passkey credential.
The vendor of the device.
The engine of the passkey credential.
The version of the engine.
The OS of the passkey credential.
The CPU of the passkey credential.
The architecture of the CPU.
The date and time the passkey credential was verified in ISO 8601 format.
authenticatorAttachment
'platform' | 'cross-platform'
The authenticator attachment of the passkey credential.
The AAGUID mapping of the passkey credential.
The name of the AAGUID mapping.
The SVG icon of the AAGUID mapping in light mode.
The SVG icon of the AAGUID mapping in dark mode.
SMS OTP
All SMS OTP SDK methods require you to set a token first .
Enroll SMS
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.
const response = await authsignal . sms . enroll ({ phoneNumber: "" + 64271234567 "" });
Parameters
Response
response
AuthsignalResponse<EnrollResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal user.
The ID of the Authsignal user authenticator.
Challenge SMS
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.
const response = await authsignal . sms . challenge ();
Response
response
AuthsignalResponse<ChallengeResponse>
An unstructured error description present if the SDK call encountered an error.
The ID of the Authsignal challenge.
Verify SMS
Finish enrolling or re-authenticating a new or existing SMS OTP authenticator by verifying the code submitted by the user.
const response = await authsignal . sms . verify ({ code: "123456" });
Parameters
The OTP code inputted by the user.
Response
response
AuthsignalResponse<VerifyResponse>
An unstructured error description present if the SDK call encountered an error.
True if the verification was successful.
Only present on first time verification e.g. enrollment.
The ID of the Authsignal user authenticator.
verificationMethod
'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PASSKEY' | 'PUSH' | 'SECURITY_KEY' | 'VERIFF' | 'IPROOV' | 'IDVERSE' | 'PALM_BIOMETRICS_BR'
required
The date and time the authenticator was created in ISO 8601 format.
The date and time the authenticator was first verified in ISO 8601 format.
The date and time the authenticator was last verified in ISO 8601 format.
Whether the authenticator is the default authenticator for the user.
The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.
The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
Only present for passkey authenticators.
The ID of the passkey credential.
The device ID of the passkey credential.
The name of the passkey credential.
The AAGUID of the passkey credential.
Whether the passkey credential is backed up.
credentialDeviceType
'singleDevice' | 'multiDevice'
The device type of the passkey credential.
The parsed user agent of the passkey credential.
The user agent of the passkey credential.
The browser of the passkey credential.
The version of the browser.
The major version of the browser.
The device of the passkey credential.
The vendor of the device.
The engine of the passkey credential.
The version of the engine.
The OS of the passkey credential.
The CPU of the passkey credential.
The architecture of the CPU.
The date and time the passkey credential was verified in ISO 8601 format.
authenticatorAttachment
'platform' | 'cross-platform'
The authenticator attachment of the passkey credential.
The AAGUID mapping of the passkey credential.
The name of the AAGUID mapping.
The SVG icon of the AAGUID mapping in light mode.
The SVG icon of the AAGUID mapping in dark mode.
A structured code present if the verification failed due to user error. Possible values are:
CODE_INVALID_OR_EXPIRED
or MAX_ATTEMPTS_EXCEEDED
.
Authenticator app (TOTP)
All authenticator app SDK methods require you to set a token first .
Enroll TOTP
Start enrollment for a new TOTP authenticator by generating a QR code to display to the user.
const response = await authsignal . totp . enroll ();
Response
response
AuthsignalResponse<EnrollTotpResponse>
An unstructured error description present if the SDK call encountered an error.
A TOTP URI which can be converted into a QR code and presented to the user to scan with
their authenticator app.
The raw TOTP secret which can be presented to the user as a fallback option if they wish to
enter a code manually instead of scanning a QR code.
Verify TOTP
Finish enrolling or re-authenticating a TOTP authenticator by verifying the code submitted by the user.
const response = await authsignal . totp . verify ({ code: "123456" });
Parameters
The OTP code inputted by the user.
Response
response
AuthsignalResponse<VerifyResponse>
An unstructured error description present if the SDK call encountered an error.
True if the verification was successful.
Only present on first time verification e.g. enrollment.
The ID of the Authsignal user authenticator.
verificationMethod
'SMS' | 'AUTHENTICATOR_APP' | 'EMAIL_MAGIC_LINK' | 'EMAIL_OTP' | 'PASSKEY' | 'PUSH' | 'SECURITY_KEY' | 'VERIFF' | 'IPROOV' | 'IDVERSE' | 'PALM_BIOMETRICS_BR'
required
The date and time the authenticator was created in ISO 8601 format.
The date and time the authenticator was first verified in ISO 8601 format.
The date and time the authenticator was last verified in ISO 8601 format.
Whether the authenticator is the default authenticator for the user.
The email address of the authenticator. Only present for email authenticators e.g. email OTP and email magic link.
The phone number of the authenticator. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
The previous SMS channel used to send the OTP code. Only present for phone authenticators e.g. SMS/WhatsApp OTP.
Only present for passkey authenticators.
The ID of the passkey credential.
The device ID of the passkey credential.
The name of the passkey credential.
The AAGUID of the passkey credential.
Whether the passkey credential is backed up.
credentialDeviceType
'singleDevice' | 'multiDevice'
The device type of the passkey credential.
The parsed user agent of the passkey credential.
The user agent of the passkey credential.
The browser of the passkey credential.
The version of the browser.
The major version of the browser.
The device of the passkey credential.
The vendor of the device.
The engine of the passkey credential.
The version of the engine.
The OS of the passkey credential.
The CPU of the passkey credential.
The architecture of the CPU.
The date and time the passkey credential was verified in ISO 8601 format.
authenticatorAttachment
'platform' | 'cross-platform'
The authenticator attachment of the passkey credential.
The AAGUID mapping of the passkey credential.
The name of the AAGUID mapping.
The SVG icon of the AAGUID mapping in light mode.
The SVG icon of the AAGUID mapping in dark mode.
A structured code present if the verification failed due to user error. Possible values are:
CODE_INVALID_OR_EXPIRED
or MAX_ATTEMPTS_EXCEEDED
.
Setting a token
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).
Node.js
C#
Java
Ruby
Python
PHP
Go
const request = {
userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833" ,
action: "signIn" ,
};
const response = await authsignal . track ( request );
const token = response . token ;
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.
authsignal . setToken ( "eyJhbGciOiJ..." );
// Send the user an email OTP code
// You can call this multiple times via a 'resend' button
await authsignal . email . challenge ();
// Verify the inputted code matches the original code
const response = await authsignal . email . verify ({ code: "123456" });
The SDK client exposes an anonymousId
property which can be used as the deviceId
when tracking an action.