Browser API
The Authsignal Browser API can be used to launch the Challenge UI to let users set up MFA and complete challenges.
Installation
To install the Authsignal client as an npm package, run:
- npm
- Yarn
- pnpm
npm install @authsignal/browser
yarn add @authsignal/browser
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://challenge.authsignal.com/v1 |
AU (Sydney) | https://au-challenge.authsignal.com/v1 |
EU (Dublin) | https://eu-challenge.authsignal.com/v1 |
launch
launch
lets you launch the Challenge 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
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 Challenge UI. |
Types
LaunchOptions
type LaunchOptions = {
/**
* How the Challenge 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;
};
};
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",
},
};
passkey.signUp
Used when taking a user through passkey enrollment.
Usage
After you have made a server-side track
call you will get back a token
that can be passed to the passkey.signUp
method.
authsignal.passkey.signUp({ token: 'TOKEN_FROM_SERVER_SIDE_TRACK_CALL'});
Arguments
Name | Type | Description |
---|---|---|
userName | string | undefined | The user's user name e.g. email. |
token | string | The token from the server-side track call. |
passkey.signIn
Used when reauthenticating a user with a passkey.
Usage
authsignal.passkey.signIn(options);
Arguments
Name | Type | Description |
---|---|---|
token | string | undefined | The token from the server-side track call. If no token is provided, then an action will be automatically created server-side. |
autofill | string | undefined | Should be set to true if wanting to use the browser's passkey autofill functionality. |