Installation

npm install @authsignal/node

Initialization

import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({ secret: "YOUR_SECRET_KEY" });

You can find your client or tenant ID in the Authsignal Portal.

You must specify the correct base URL for your tenant’s region.

RegionBase URL
US (Oregon)https://api.authsignal.com/v1
AU (Sydney)https://au.api.authsignal.com/v1
EU (Dublin)https://eu.api.authsignal.com/v1

For example, to set the base URL to use our AU region:

import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({
  secret: "YOUR_SECRET_KEY",
  apiBaseUrl: "https://au.api.authsignal.com/v1",
});

track

track lets you record actions performed by users and initiate challenges.

const result = await authsignal.track({
  userId: "usr_123",
  action: "withdrawal",
  redirectUrl: "https://example.com/finalize-withdrawal",
});

if (result.state === "CHALLENGE_REQUIRED") {
  // The user should be presented with a challenge
}

Arguments

Returns

validateChallenge

validateChallenge lets you validate the result of a challenge using the token which is obtained after a redirect (if using the pre-built UI) or returned by a client SDK (if using an embedded flow).

const result = await authsignal.validateChallenge({ token });

if (result.state === "CHALLENGE_SUCCEEDED") {
  // The user completed the challenge successfully
}

When performing MFA for a user who has already been authenticated by a primary factor (e.g. username & password), it’s important to check the token belongs to that user. The validateChallenge method will do this check if you pass both the token and the userId.

Arguments

Returns

getUser

getUser retrieves a user and their MFA enrollment status.

const result = await authsignal.getUser({ userId: "usr_123" });

if (result.isEnrolled) {
  // The user has set up MFA and can be challenged
} else {
  // The user has either not set up MFA or they have disabled it
}

Arguments

Returns

getAction

getAction lets you determine the result of a challenge after the user has been redirected back from the Authsignal pre-built UI (or after the popup has been closed, if showing the page in a modal).

const result = await authsignal.getAction({
  userId: "usr_123",
  action: "signIn",
  idempotencyKey: "ik_123",
});

if (result.state === "CHALLENGE_SUCCEEDED") {
  // The user successfully completed the challenge
  // Proceed with the withdrawal
}

Arguments

Returns

enrollVerifiedAuthenticator

enrollVerifiedAuthenticator can be used to enroll an authenticator on behalf of a user if it has already been verified.

await authsignal.enrollVerifiedAuthenticator({
  userId: "usr_123",
  oobChannel: "SMS",
  phoneNumber: "+64271234567",
});

Arguments

Returns

authenticator
object
recoveryCodes
string[]