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.

RegionBase 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

url
string

The URL which was returned as the result of a track request made using the Authsignal Server API.

options
LaunchOptions Object

The options used when launching the pre-built UI.

Returns

Promise<TokenPayload>

When mode is set as popup it returns a Promise<TokenPayload> that resolves when the popup closes.

token
string

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.

EnrollResponse
uri
string

This can be encoded as a QR code to be scanned by an authenticator app.

secret
string

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

code
string

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.

VerifyResponse
isVerified
boolean

Whether the TOTP code was verified successfully.

failureReason
'CODE_INVALID_OR_EXPIRED' | 'MAX_ATTEMPTS_EXCEEDED'

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

email
string

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.

EnrollResponse
userAuthenticatorId
string

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

code
string

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.

VerifyResponse
isVerified
boolean

Whether the TOTP code was verified successfully.

failureReason
'CODE_INVALID_OR_EXPIRED' | 'MAX_ATTEMPTS_EXCEEDED'

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

phoneNumber
string

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.

EnrollResponse
userAuthenticatorId
string

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

code
string

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.

VerifyResponse
isVerified
boolean

Whether the TOTP code was verified successfully.

failureReason
'CODE_INVALID_OR_EXPIRED' | 'MAX_ATTEMPTS_EXCEEDED'

The reason the TOTP code verification failed.

Was this page helpful?