Web
Learn how to use the Authsignal Web SDK.
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
This will add our module to your package.json
.
Initialization
Initialize the client with your tenant ID and the API URL for your region.
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.
Parameters
The URL obtained on your server by tracking an action.
The options used when launching the pre-built UI.
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.
Parameters
A short-lived token obtained by tracking an action.
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.
Response
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.
Passkeys represent a new paradigm when compared with traditional authentication methods. To learn more about how to create an optimal sign-in experience for users, refer to our documentation on best practices for passkeys in web browsers.
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
Using passkey autofill
This feature requires rendering a text input with the attribute autocomplete="username webauthn"
:
Then when the page loads you should initialize the input for passkey autofill by running the following code.
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 tosignUp
). 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.
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.
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.
Parameters
The user’s email address.
Response
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.
Response
Verify email
Finish enrolling or re-authenticating a new or existing email OTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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.
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.
Parameters
The user’s email address.
Response
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.
Response
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.
Response
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.
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.
Parameters
The user’s phone number in E.164 format e.g. +14155552671.
Response
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.
Response
Verify SMS
Finish enrolling or re-authenticating a new or existing SMS OTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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.
Response
Verify TOTP
Finish enrolling or re-authenticating a TOTP authenticator by verifying the code submitted by the user.
Parameters
The OTP code inputted by the user.
Response
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).
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.
Extras
The SDK client exposes an anonymousId
property which can be used as the deviceId
when tracking an action.
Was this page helpful?