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.
Concepts
Section titled “Concepts”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.
Required Secret
Section titled “Required Secret”Production deployments should set:
TOTP_SECRET_ENCRYPTION_KEY=replace-with-long-random-secretThe 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.
Step 1: Use Passkey Step-Up In React
Section titled “Step 1: Use Passkey Step-Up In React”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:
stepUpStatusrefreshStepUpStatus()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-replacementThrough the Express adapter, the browser-facing route is:
POST /auth/admin/users/:userId/recovery/device-replacementThat route requires:
- authenticated access session
admin:writeor 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.
Step 3: Read Step-Up Status
Section titled “Step 3: Read Step-Up 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.
Step 4: Understand TOTP Route Contracts
Section titled “Step 4: Understand TOTP Route Contracts”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.
Step 5: Build TOTP Enrollment UI
Section titled “Step 5: Build TOTP Enrollment UI”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)}Step 6: Use TOTP For Step-Up
Section titled “Step 6: Use TOTP For Step-Up”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.
Step 7: Handle Login MFA
Section titled “Step 7: Handle Login MFA”/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.
Common Mistakes
Section titled “Common Mistakes”| 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 |