Web

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.

​

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.

​

Arguments

​

Returns

​

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();

​

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.

​

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

​

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.

​

Email OTP

​

Adding an Email OTP authenticator

enroll lets you create a new Email OTP authenticator.

const result = await authsignal.email.enroll({ email });

​

Arguments

​

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.

​

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

​

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.

​

SMS OTP

​

Adding an SMS OTP authenticator

enroll lets you create a new SMS OTP authenticator.

const result = await authsignal.SMS.enroll({ phoneNumber });

​

Arguments

​

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.

​

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

​

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.