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

npm install @authsignal/browser

This will add our module to your package.json.

​

Initialization

Initialize the client with your tenant ID and the API 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

​

Response

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.

const response = await authsignal.passkey.signUp({
  token: "eyJhbGciOiJ...",
  username: "jane@authsignal.com",
  displayName: "Jane Smith",
});

​

Parameters

​

Response

​

Automatic passkey upgrades

With passkey upgrades, your app can prompt your user’s password manager to automatically create a passkey. This works provided the user has a password saved for your app in their password manager and has recently authenticated with it.

To enable this, you must set the useAutoRegister parameter to true when calling signUp.

const response = await authsignal.passkey.signUp({
  token: "eyJhbGciOiJ...",
  username: "jane@authsignal.com",
  displayName: "Jane Smith",
  useAutoRegister: true,
});

​

Example usage

async function onSubmit(formData) {
  // Validate user on BE and return a token from `track`

  // If valid user, attempt to automatically create a passkey  
  try {
    const response = await authsignal.passkey.signUp({
      token: "eyJhbGciOiJ...", // Token from `track`
      username: "jane@authsignal.com",
      displayName: "Jane Smith",
      useAutoRegister: true,
    });
  } catch (error) {
    // Failed to automatically create a passkey
    console.error(error);
  }
  
  // Continue with post-sign-in flow
  window.location.href = "/dashboard";
}

​

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" />

It can also be added to a password input:

<input type="password" id="password" autocomplete="current-password 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
    }
  });

​

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

import { WebAuthnError } from "@authsignal/browser";

try {
  const response = await authsignal.passkey.signUp({
    token: "eyJhbGciOiJ...",
    username: "jane@authsignal.com",
    displayName: "Jane Smith",
  });
} catch (error) {
  if (error instanceof WebAuthnError) {
    if (error.code === "ERROR_AUTHENTICATOR_PREVIOUSLY_REGISTERED") {
      // The user already has a passkey registered for this authenticator
      // You can choose to handle this however you see fit
    }
  }
}

​

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

​

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.

const response = await authsignal.emailML.enroll({ email: "jane@authsignal.com" });

​

Parameters

​

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.

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

​

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.

const response = await authsignal.emailML.checkVerificationStatus();

​

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

const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
};

const response = await authsignal.track(request);

const token = response.token;

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;