Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Portal setup

  1. Navigate to Authenticators in the Authsignal Portal and click on Authenticator app (TOTP).
  2. Activate the authenticator in the next screen.

​
SDK setup

​
Server SDK

Initialize the SDK using your secret key from the API keys page and the API URL for your region. 
import { Authsignal } from "@authsignal/node";

const authsignal = new Authsignal({
  apiSecretKey: "YOUR_SECRET_KEY",
  apiUrl: "YOUR_API_URL",
});

​
Client SDK

Initialize the Web SDK or Mobile SDK using your tenant ID from the API keys page and your API URL. 
import { Authsignal } from "@authsignal/browser";

const authsignal = new Authsignal({
  tenantId: "YOUR_TENANT_ID",
  baseUrl: "YOUR_API_URL",
});

​
Adaptive MFA

The following steps demonstrate how to implement adaptive MFA with authenticator app - either at sign-in or as step-up authentication when the user performs a sensitive action in your app (e.g. making a payment).

​
1. Track action

Use a Server SDK to track an action in your backend. This step can apply rules to determine if a challenge is required. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "signIn",
};

const response = await authsignal.track(request);

const token = response.token;
You can choose a value for the action here which best describes what the user is doing in your app (e.g. signIn or createPayment). Each action can have its own set of rules. To learn more about using rules and handling different action states refer to our documentation on actions and rules.

​
2. Present challenge

If the action state is CHALLENGE_REQUIRED then you can present an authenticator app challenge using the Web SDK or Mobile SDK. 
// Set token from the track response
authsignal.setToken("eyJhbGciOiJ...");

// Verify the TOTP code inputted by the user
const response = await authsignal.totp.verify({ code: "123456" });

// Obtain a new token
const token = response.token;

​
3. Validate action

Use the new token obtained from the client SDK to validate the action on your backend. 
const response = await authsignal.validateChallenge({
  action: "signIn",
  token: "eyJhbGciOiJIUzI....",
});

if (response.state === "CHALLENGE_SUCCEEDED") {
  // User completed challenge successfully
}
If the action state shows that the authenticator app challenge was completed successfully, you can let the user proceed with the action.

​
Enrollment

The following steps demonstrate how to let users enroll an authenticator app by scanning a QR code.

​
1. Track action

Use a Server SDK to track an action in your backend. 
const request = {
  userId: "dc58c6dc-a1fd-4a4f-8e2f-846636dd4833",
  action: "enroll",
};

const response = await authsignal.track(request);

const token = response.token;
You can choose any value for the action here which describes the enrollment flow. This will be used to track the enrollment activity in the Authsignal Portal.
If the user is already enrolled with another authentication method, you will need to pass additional scopes when tracking this action - refer to our documentation on authenticator binding for more information.

​
2. Present QR code

Use the Web SDK or Mobile SDK to present a QR code which the user can scan with their authenticator app. 
// Set token from the track response
authsignal.setToken("eyJhbGciOiJ...");

const response = await authsignal.totp.enroll();

if (response.data) {
  const uri = response.data.uri; // Convert to QR code
  const secret = response.data.secret; // Can be entered manually
}

​
3. Verify

Use the Web SDK or Mobile SDK to verify the code submitted by the user to complete enrollment. 
const response = await authsignal.totp.verify({ code: "123456" });

​
Next steps

  • Pre-built UI - Rapidly deploy authenticator app challenges using our pre-built UI
  • Web SDK - Implement authenticator app challenges while building your own UI
  • Mobile SDK - Implement authenticator app challenges in native mobile apps
  • Adaptive MFA - Set up smart rules to trigger authentication based on risk
  • Passkeys - Offer the most secure and user-friendly passwordless authentication