Skip to content

How To Use TOTP And Step-Up

Use this guide when you need authenticator-app MFA or fresh verification before sensitive actions.

There are three related surfaces:

Surface Current high-level support
WebAuthn step-up @seamless-auth/react, the server adapters, and seamless-auth-api
TOTP enrollment, status, disable, and step-up @seamless-auth/react, the server adapters, and seamless-auth-api
TOTP login MFA seamless-auth-api raw route only

The React SDK wraps TOTP. The headless client (useAuthClient() or createSeamlessAuthClient()) exposes getTotpStatus(), startTotpEnrollment(), verifyTotpEnrollment(code), disableTotp(code), and verifyStepUpWithTotp(code), and useAuth() exposes verifyStepUpWithTotp(code). The Express, Fastify, and Next.js adapters mount the matching /auth/totp/* routes, so no backend code is needed. Only TOTP login MFA is still unwrapped.

Every one of these methods resolves to { data, error }. See Reading Results if that pattern is new to you.


TOTP is an authenticator-app secret stored for a user. It supports:

  • enrollment
  • login MFA
  • disabling TOTP
  • TOTP-backed step-up verification

Step-up is a session freshness marker. When a user completes WebAuthn or TOTP step-up, the auth API records stepUpVerifiedAt and stepUpMethod on the current session.

The default freshness window is five minutes.


Production deployments should set:

TOTP_SECRET_ENCRYPTION_KEY=replace-with-long-random-secret

The auth API uses this to encrypt TOTP secrets at rest. If it is unset, the API can fall back to API_SERVICE_TOKEN; production requires one of those stable values.


For sensitive UI actions, first check whether the current session is already fresh.

import { useAuth } from '@seamless-auth/react'
export function SensitiveActionButton() {
const { refreshStepUpStatus, verifyStepUpWithPasskey } = useAuth()
async function run() {
const { data } = await refreshStepUpStatus()
let fresh = data?.fresh === true
if (!fresh) {
const { error } = await verifyStepUpWithPasskey()
fresh = !error
}
if (!fresh) {
return
}
await fetch('/auth/admin/users/user_123/recovery/device-replacement', {
method: 'POST',
credentials: 'include',
})
}
return <button onClick={() => void run()}>Recover device</button>
}

data is null when the status request fails, hence data?.fresh. A passkey prompt the user dismisses comes back as error, so fresh stays false and the action does not run.

useAuth() exposes:

  • stepUpStatus
  • refreshStepUpStatus()
  • verifyStepUpWithPasskey()
  • verifyStepUpWithPasskeyPrf(input)
  • verifyStepUpWithTotp(code)

Step 2: Know Which Built-In Routes Require Step-Up

Section titled “Step 2: Know Which Built-In Routes Require Step-Up”

The auth API currently enforces step-up on admin-assisted device replacement:

POST /admin/users/:userId/recovery/device-replacement

Through the Express adapter, the browser-facing route is:

POST /auth/admin/users/:userId/recovery/device-replacement

That route requires:

  • authenticated access session
  • admin:write or equivalent scoped admin access
  • fresh step-up authentication

If step-up is missing or stale, the auth API returns 403 with error: "step_up_required" and the current freshness status.


Through the React SDK:

const { data, error } = await refreshStepUpStatus()
if (!error && data.fresh) {
console.log(data.method, data.expiresAt)
}

data has this shape, which is also the raw response body:

{
"fresh": true,
"method": "webauthn",
"verifiedAt": "2026-05-30T12:00:00.000Z",
"expiresAt": "2026-05-30T12:05:00.000Z",
"maxAgeSeconds": 300
}

method can be webauthn, totp, or null.


The raw auth API exposes:

Method Route Auth Purpose
GET /totp/status access bearer Get current user’s TOTP status
POST /totp/enroll/start access bearer Create pending TOTP enrollment
POST /totp/enroll/verify access bearer Verify and enable enrollment
POST /totp/disable access bearer Disable TOTP
POST /totp/verify-login ephemeral bearer Verify TOTP during login
POST /totp/verify-mfa access bearer Verify TOTP for MFA or step-up

The Express, Fastify, and Next.js adapters mount every route except /totp/verify-login under /auth/totp/*, authenticated by the access cookie, and the SDK methods call those adapter routes. This table is reference for what travels on the wire.

Verification requests use:

{
"code": "123456"
}

Enrollment start returns:

{
"message": "Success",
"secret": "BASE32SECRET",
"otpauthUrl": "otpauth://totp/...",
"issuer": "Your App",
"accountName": "user@example.com",
"algorithm": "SHA1",
"digits": 6,
"period": 30
}

Show otpauthUrl as a QR code, or show secret for manual authenticator-app entry. Do not log or store either value in frontend analytics.


Enrollment needs a signed-in session. Start it, show the secret, then confirm it with a code from the authenticator app.

import { useState } from 'react'
import { useAuthClient, type TotpEnrollmentStartResult } from '@seamless-auth/react'
export function TotpEnrollment() {
const authClient = useAuthClient()
const [enrollment, setEnrollment] = useState<TotpEnrollmentStartResult | null>(null)
const [code, setCode] = useState('')
const [message, setMessage] = useState('')
async function start() {
const { data, error } = await authClient.startTotpEnrollment()
if (error) {
setMessage(error.message)
return
}
setEnrollment(data)
}
async function verify() {
const { error } = await authClient.verifyTotpEnrollment(code)
if (error) {
setMessage(error.message)
return
}
setEnrollment(null)
setMessage('Authenticator app enabled.')
}
return (
<section>
<button onClick={() => void start()}>Set up authenticator app</button>
{enrollment && (
<>
<p>{enrollment.accountName}</p>
<code>{enrollment.secret}</code>
<input value={code} onChange={(event) => setCode(event.target.value)} />
<button onClick={() => void verify()}>Verify</button>
</>
)}
{message && <p>{message}</p>}
</section>
)
}

data from startTotpEnrollment() is the enrollment start body shown in Step 4. For production UI, render otpauthUrl as a QR code and keep the manual secret behind a secondary action.

Read the current status with the same client. data is { enabled, verifiedAt, lastUsedAt }:

const { data, error } = await authClient.getTotpStatus()
if (!error && data.enabled) {
console.log(data.verifiedAt, data.lastUsedAt)
}

Disabling needs a current code from the authenticator app:

const { error } = await authClient.disableTotp(code)
if (error) {
setMessage(error.message)
}

After a user has enabled TOTP, verifyStepUpWithTotp(code) marks the current session fresh.

import { useState } from 'react'
import { useAuth } from '@seamless-auth/react'
export function TotpStepUp({ onVerified }: { onVerified: () => void }) {
const { verifyStepUpWithTotp } = useAuth()
const [code, setCode] = useState('')
const [message, setMessage] = useState('')
async function verify() {
const { error } = await verifyStepUpWithTotp(code)
if (error) {
setMessage(error.message)
return
}
onVerified()
}
return (
<>
<input value={code} onChange={(event) => setCode(event.target.value)} />
<button onClick={() => void verify()}>Verify</button>
{message && <p>{message}</p>}
</>
)
}

On success, data is the step-up status from Step 3 with method: "totp", and stepUpStatus on useAuth() updates to match. A response that does not report a fresh TOTP verification comes back as error, so checking error is enough.


/totp/verify-login uses an ephemeral bearer token from the login pre-auth flow. It is the one TOTP route that the SDK does not wrap and the adapters do not mount, and there is no packaged TOTP login UI. If you add one today, keep it behind a backend bridge that forwards the pre-auth bearer token the same way the adapter forwards OTP and WebAuthn login routes.

Until the adapter exposes this route directly, prefer documenting TOTP login MFA as an advanced integration point rather than assuming it is available in the packaged React screens.


Fallback: A Backend Bridge Without An Adapter

Section titled “Fallback: A Backend Bridge Without An Adapter”

A backend without an adapter has to forward TOTP requests itself. One option is to verify the signed access cookie, extract the upstream bearer token stored inside that cookie, and forward the request to seamless-auth-api.

import express from 'express'
import { authFetch, verifyCookieJwt } from '@seamless-auth/core'
const totpRouter = express.Router()
function getAccessAuthorization(req: express.Request) {
const cookieValue = req.cookies?.['seamless-access']
const payload = cookieValue
? verifyCookieJwt<{ token?: string }>(cookieValue, process.env.COOKIE_SIGNING_KEY!)
: null
if (!payload?.token) {
return null
}
return `Bearer ${payload.token}`
}
totpRouter.use(express.json())
async function forwardAccessTotp(
req: express.Request,
res: express.Response,
path: string,
method: 'GET' | 'POST',
) {
const authorization = getAccessAuthorization(req)
if (!authorization) {
res.status(401).json({ error: 'unauthorized' })
return
}
const upstream = await authFetch(`${process.env.AUTH_SERVER_URL}/totp/${path}`, {
method,
authorization,
...(method === 'POST' ? { body: req.body } : {}),
})
res.status(upstream.status).json(await upstream.json())
}
totpRouter.get('/status', async (req, res) => {
await forwardAccessTotp(req, res, 'status', 'GET')
})
totpRouter.post('/enroll/start', async (req, res) => {
await forwardAccessTotp(req, res, 'enroll/start', 'POST')
})
totpRouter.post('/enroll/verify', async (req, res) => {
await forwardAccessTotp(req, res, 'enroll/verify', 'POST')
})
totpRouter.post('/disable', async (req, res) => {
await forwardAccessTotp(req, res, 'disable', 'POST')
})
totpRouter.post('/verify-mfa', async (req, res) => {
await forwardAccessTotp(req, res, 'verify-mfa', 'POST')
})
app.use('/auth/totp', totpRouter)

Keep this bridge server-side. Do not expose the upstream bearer token to browser JavaScript. Mount it at /auth/totp so the SDK methods above reach it unchanged.


Mistake Fix
Writing a TOTP backend bridge next to an adapter The adapters already mount /auth/totp/*; call the SDK methods
Looking for TOTP enrollment on useAuth() Enrollment, status, and disable are on useAuthClient(); step-up is on both
Calling raw TOTP routes from browser code without bearer handling Use the SDK through your adapter; keep bearer tokens server-side
Logging secret or otpauthUrl Treat enrollment values as sensitive
Using TOTP step-up without an enabled credential Check getTotpStatus() first and read data.enabled
Treating UI freshness as authorization Let the auth API or your backend enforce sensitive actions