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
- 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://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.
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
}
});