This guide shows how to implement TOTP authenticator apps for MFA. You can follow the same approach for step-up auth or adaptive MFA.

​
Configure TOTP in the Authsignal Portal

  1. Navigate to the Authenticators section and click Manage Authenticator App.
  2. Activate the TOTP authenticator in the next screen.

​
Grab your Authsignal credentials

Head to Settings and grab your Tenant ID, API URL and API secret key. Add them as environment variables in your project: 
AUTHSIGNAL_API_URL=your_region_api_url
AUTHSIGNAL_TENANT_ID=your_tenant_id
AUTHSIGNAL_SECRET_KEY=your_secret_key

​
Implementation

​
1. Backend - Track an action

When a user performs an action that requires authentication, your backend should track the action. You can use our Server SDK or Server API to track the action. The code snippets in this guide references the SDKs. 
import { Authsignal } from '@authsignal/node';

const authsignal = new Authsignal({
  apiSecretKey: process.env.AUTHSIGNAL_SECRET_KEY,
});

// Track the sign-in action
const trackResponse = await authsignal.track({
  userId: 'dc58c6dc-a1fd-4a4f-8e2f-846636dd4833',
  action: 'signIn',
});

// Handle different action outcomes
if (trackResponse.state === 'CHALLENGE_REQUIRED') {
  // User needs to complete TOTP challenge
  return { token: trackResponse.token };
} else if (trackResponse.state === 'ALLOW') {
  // Proceed with the action - no challenge needed
  return { success: true };
} else if (trackResponse.state === 'BLOCK') {
  // Block the action for security reasons
  return { error: 'Action blocked for security reasons' };
}
Understanding action statesWhen you track an action, Authsignal returns one of four possible states:
  • CHALLENGE_REQUIRED - User must complete an authentication challenge (proceed to step 2)
  • ALLOW - Action is permitted without additional authentication
  • BLOCK - Action is blocked for security reasons
  • REVIEW - Action requires manual review
Learn more about action outcomes.

​
2. Frontend - Challenge the user

If the action state is CHALLENGE_REQUIRED, proceed with the TOTP challenge using either our Web SDK, Mobile SDKs or Client API. 
import { Authsignal } from '@authsignal/browser';

const authsignal = new Authsignal({
  tenantId: 'YOUR_TENANT_ID',
});

// Set the token from the track response
authsignal.setToken(token);

// For enrollment: Generate QR code and secret first
// Only needed if user doesn't have TOTP set up yet
const enrollResponse = await authsignal.totp.enroll();

if (enrollResponse.data) {
  const qrCodeUri = enrollResponse.data.uri; // Display as QR code
  const secret = enrollResponse.data.secret; // Fallback manual entry
  
  // Display QR code to user for them to scan with their authenticator app
}

// For both enrollment and re-authentication:
// User enters the TOTP code from their authenticator app
const verifyResponse = await authsignal.totp.verify({ 
  code: userEnteredCode 
});

// Get the verification token to validate on your backend
if (verifyResponse.data?.isVerified) {
  const verificationToken = verifyResponse.data.token;
}

​
3. Backend - Validate the challenge

After the user completes the challenge, validate the token on your backend: 
import { Authsignal } from '@authsignal/node';

const authsignal = new Authsignal({
  apiSecretKey: process.env.AUTHSIGNAL_SECRET_KEY,
});

// Validate the challenge token
const validationResult = await authsignal.validateChallenge({ token });

if (validationResult.isValid) {
  // Authentication successful - proceed with user session creation
  return { success: true };
}
That’s it! You’ve successfully implemented TOTP authenticator app authentication with Authsignal.

​
Next steps

  • Adaptive MFA - Set up smart rules to trigger authentication based on risk
  • Email OTP - Add email-based OTP codes as an alternative method
  • SMS OTP - Add SMS-based OTP codes as another option
  • Passkeys - Offer the most secure and user-friendly passwordless authentication