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 adding and verifying authenticators
Installation
To install the Authsignal client as an npm package, run:
npm install @authsignal/browser
This will add our browser library module to your package.json
.
Then you can initialize the Authsignal browser client in your code:
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 | Base URL |
---|---|
US (Oregon) | https://api.authsignal.com/v1 |
AU (Sydney) | https://au.api.authsignal.com/v1 |
EU (Dublin) | https://eu.api.authsignal.com/v1 |
anonymousId
The anonymous ID of the user’s device. This can be used as the deviceId
included in a track action call.
authsignal.anonymousId;
launch
launch
lets you launch the pre-built UI.
authsignal.launch(url, options);
Usage
After you’ve made a server-side track
call you’ll get back a url
which you can pass to the Browser API’s launch
function.
pre-built UI launched in popup mode
pre-built UI launched with a redirect
Arguments
The URL which was returned as the result of a track
request made using the
Authsignal Server API.
The options used when launching the pre-built UI.
Returns
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.
Passkeys
For more information visit our passkeys documentation.
Registering a new passkey
const resultToken = await authsignal.passkey.signUp({ token, userName });
Authenticating with an existing passkey
const resultToken = await authsignal.passkey.signIn({ token });
Using passkey autofill
This feature requires rendering a text input with the attribute autocomplete="username webauthn"
:
<input type="text" id="username" autocomplete="username webauthn" />
Then when the page loads, you should initialize the input for passkey autofill by running the following code:
authsignal.passkey.signIn({ autofill: true }).then((resultToken) => {
if (resultToken) {
// 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
}
});
setToken
Authsignal’s Web SDK methods require a token
to be set before making any requests. This token
should be passed from your
server as a result of a track action request.
// before calling in any SDK methods, set the token
authsignal.setToken(token);
// then you can use the SDK methods e.g.
const result = await authsignal.totp.enroll();
Make sure your token
has the correct
scopes for the action
you are trying to perform.
Authenticator app (TOTP)
Adding an authenticator app
enroll
lets you create a new TOTP authenticator.
const result = await authsignal.totp.enroll();
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<EnrollResponse>
object.
If the TOTP authenticator is created successfully, an EnrollResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
This can be encoded as a QR code to be scanned by an authenticator app.
This can be pasted directly into an authenticator app as an alternative to scanning the QR code.
Verifying a TOTP code
verify
lets you verify a TOTP code. This is required after creating a new TOTP authenticator with enroll
and
when requiring users to complete a TOTP challenge.
const result = await authsignal.totp.verify({ code });
Arguments
The TOTP code entered by the user.
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<VerifyResponse>
object.
If the TOTP code is submitted successfully, a VerifyResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
Whether the TOTP code was verified successfully.
The reason the TOTP code verification failed.
Email OTP
Adding an Email OTP authenticator
enroll
lets you create a new Email OTP authenticator.
const result = await authsignal.email.enroll({ email });
Arguments
The user’s email address.
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<EnrollResponse>
object.
If the Email OTP authenticator is created successfully, an EnrollResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
The ID of the created Email OTP authenticator.
Initiating an Email OTP challenge
challenge
lets you initiate an Email OTP challenge. An OTP code will be sent to the user’s email address.
Verifying an OTP code
verify
lets you verify an OTP code. This is required after creating a new Email OTP authenticator with enroll
and
when requiring users to complete an Email OTP challenge.
const result = await authsignal.email.verify({ code });
Arguments
The OTP code entered by the user.
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<VerifyResponse>
object.
If the OTP code is submitted successfully, a VerifyResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
Whether the TOTP code was verified successfully.
The reason the TOTP code verification failed.
SMS OTP
Adding an SMS OTP authenticator
enroll
lets you create a new SMS OTP authenticator.
const result = await authsignal.SMS.enroll({ phoneNumber });
Arguments
The user’s phone number.
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<EnrollResponse>
object.
If the SMS OTP authenticator is created successfully, an EnrollResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
The ID of the created SMS OTP authenticator.
Initiating an SMS OTP challenge
challenge
lets you initiate an SMS OTP challenge. An OTP code will be sent to the user’s phone.
Verifying an OTP code
verify
lets you verify an OTP code. This is required after creating a new SMS OTP authenticator with enroll
and
when requiring users to complete an SMS OTP challenge.
const result = await authsignal.sms.verify({ code });
Arguments
The OTP code entered by the user.
Returns
This method returns a Promise
. The promise resolves with an AuthsignalResponse<VerifyResponse>
object.
If the OTP code is submitted successfully, a VerifyResponse
object is returned. Otherwise, an
ErrorResponse
object is returned.
Whether the TOTP code was verified successfully.
The reason the TOTP code verification failed.
Was this page helpful?