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

Installation

To install the Authsignal client as an npm package, run:

npm

npm install @authsignal/browser

Yarn

yarn add @authsignal/browser

pnpm

pnpm add @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

Name	Type	Description
url	string	The URL which was returned as the result of a track request made using the Authsignal Server API.
options	LaunchOptions | undefined	The options used when launching the pre-built UI.

Types

LaunchOptions

type LaunchOptions = {
  /**
   *  How the pre-built UI should launch.
   *  `popup` will cause it to open in a overlay, whilst `redirect`
   *  will trigger a full page redirect.
   *  If no value is supplied, mode defaults to `redirect`.
   */
  mode?: "popup" | "redirect";
  popupOptions?: {
    /** Any valid CSS value for the `width` property. */
    width: string;
    /** Whether the popup is closable with the escape key and by clicking the backdrop. */
    isClosable?: boolean;
  };
};

TokenPayload

type TokenPayload = {
  token?: string;
};

Returns

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

TokenPayload is an object with a token property that can be used to verify the outcome of the user action.

Configuration options

popupOptions

Contains optional popup configuration. Has width which accepts any valid value for its respective CSS property. Note that popupOptions is only available when mode is set to popup.

const options: LaunchOptions = {
  mode: "popup",
  popupOptions: {
    width: "500px",
  },
};

If you want to disable the ability to close the popup by clicking the backdrop or pressing the escape key, you can set isClosable to false:

const options: LaunchOptions = {
  mode: "popup",
  popupOptions: {
    isClosable: false,
  },
};

Passkeys

For more detail on passkeys refer to our getting started guide.

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