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 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 base 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.

​

Launching the pre-built UI

The Web SDK can be used to launch the pre-built UI.

authsignal.launch(url, options);

​

Parameters

​

Returns

For more information on launching the pre-built UI see our detailed guide.

​

Passkeys

For more information visit our passkeys documentation.

​

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

​

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.

const response = await authsignal.passkey.signIn({ action: "signInWithPasskey" });

if (response.token) {
  // Send token to your server to validate the result
}

​

Parameters

​

Response

​

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

​

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

​

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.

const response = await authsignal.email.challenge();

​

Response

​

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

​

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.

const response = await authsignal.sms.enroll({ phoneNumber: ""+64271234567"" });

​

Parameters

​

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.

const response = await authsignal.sms.challenge();

​

Response

​

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

​

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.

const response = await authsignal.totp.enroll();

​

Response

​

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

​

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).

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" });

​

Extras

The SDK client exposes an anonymousId property which can be used as the deviceId when tracking an action.

authsignal.anonymousId;