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

In your app’s backend, track an action using Authsignal’s Server SDK:

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 states

When 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:

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