Enroll TOTP
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/totp/enroll |
| Auth | App credentials |
| Description | Start TOTP enrollment. Returns secret and QR code once. |
Request body
| Field | Type | Required |
|---|---|---|
label |
string | No |
reset |
boolean | No |
Sample success response 200
{
"ok": true,
"enrollment_id": "auth_enr_507f1f77bcf86cd799439013",
"status": "pending",
"factor_type": "totp",
"secret": "YOUR_TOTP_SECRET",
"otpauth_url": "otpauth://totp/Acme%20Admin:user_123?secret=YOUR_TOTP_SECRET&issuer=Acme%20Admin&digits=6&period=30",
"qr_code_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"pending_expires_at": "2026-07-09T12:00:00.000Z"
}
Common errors: 409 AUTH_ENROLLMENT_ALREADY_ACTIVE, 404 AUTH_APP_NOT_FOUND
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/totp/enroll" \
-H "Authorization: Bearer YOUR_APP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "user@example.com"}'
Confirm TOTP Enrollment
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/totp/confirm |
| Auth | App credentials |
| Description | Confirm enrollment with the first valid 6-digit TOTP code from the authenticator app. |
Request body: code (string, required)
Sample success response 200
{
"ok": true,
"verified": true,
"enrollment_status": "active",
"activated_at": "2026-07-09T10:45:00.000Z"
}
Common errors: 400 AUTH_INVALID_CODE, 410 AUTH_ENROLLMENT_EXPIRED, 409 AUTH_ENROLLMENT_PENDING
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/totp/confirm" \
-H "Authorization: Bearer YOUR_APP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "123456"}'
Verify TOTP
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/totp/verify |
| Auth | App credentials |
| Description | Verify TOTP code during login. Call after your backend validates the user's password. |
Request body: code (string, required)
Sample success response 200
{
"ok": true,
"verified": true,
"method": "totp",
"enrollment_status": "active",
"verified_at": "2026-07-09T11:30:00.000Z",
"recovery_codes_remaining": 8
}
Common errors: 400 AUTH_INVALID_CODE, 409 AUTH_REPLAY_DETECTED, 423 AUTH_USER_LOCKED, 404 AUTH_MFA_NOT_ENABLED
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/totp/verify" \
-H "Authorization: Bearer YOUR_APP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "654321"}'
Disable TOTP
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/totp/disable |
| Auth | App credentials |
| Description | Disable TOTP MFA for a user. |
Sample success response 200
{
"ok": true,
"disabled": true
}
Common errors: 404 AUTH_MFA_NOT_ENABLED
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/totp/disable" \
-H "Authorization: Bearer YOUR_APP_API_KEY"
Reset TOTP
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/totp/reset |
| Auth | App credentials |
| Description | Reset TOTP secret and start new enrollment. Invalidates existing recovery codes. |
Request body: label (optional string)
Sample success response 200
{
"ok": true,
"enrollment_id": "auth_enr_507f1f77bcf86cd799439014",
"status": "pending",
"factor_type": "totp",
"secret": "YOUR_TOTP_SECRET",
"otpauth_url": "otpauth://totp/Acme%20Admin:user_123?secret=YOUR_TOTP_SECRET&issuer=Acme%20Admin&digits=6&period=30",
"qr_code_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"pending_expires_at": "2026-07-09T12:00:00.000Z"
}
Common errors: 404 AUTH_USER_NOT_FOUND
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/totp/reset" \
-H "Authorization: Bearer YOUR_APP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"label": "user@example.com"}'
Recovery Codes#
Generate Recovery Codes
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/recovery-codes |
| Auth | App credentials |
| Description | Generate backup recovery codes. Codes shown once; previous batch invalidated. |
Sample success response 200
{
"ok": true,
"codes": [
"YOUR_RECOVERY_CODE",
"mnop-qrst-uvwx",
"yzab-cdef-ghij",
"klmn-opqr-stuv",
"wxyz-abcd-efgh",
"ijkl-mnop-qrst",
"uvwx-yzab-cdef",
"ghij-klmn-opqr",
"stuv-wxyz-abcd",
"efgh-ijkl-mnop"
],
"batch_id": "auth_rcb_507f1f77bcf86cd799439016",
"count": 10
}
Common errors: 404 AUTH_MFA_NOT_ENABLED
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/recovery-codes" \
-H "Authorization: Bearer YOUR_APP_API_KEY"
Verify Recovery Code
| Method | POST |
| Path | /auth/apps/:appId/users/:externalUserId/mfa/recovery-codes/verify |
| Auth | App credentials |
| Description | Verify a one-time recovery code during login. |
Request body: code (string, required)
Sample success response 200
{
"ok": true,
"verified": true,
"method": "recovery_code",
"enrollment_status": "active",
"verified_at": "2026-07-09T11:35:00.000Z",
"recovery_codes_remaining": 7
}
Common errors: 400 AUTH_RECOVERY_CODE_INVALID, 409 AUTH_RECOVERY_CODE_USED, 423 AUTH_USER_LOCKED
cURL
curl -X POST "https://api.example.com/auth/apps/auth_app_507f1f77bcf86cd799439011/users/user_123/mfa/recovery-codes/verify" \
-H "Authorization: Bearer YOUR_APP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "YOUR_RECOVERY_CODE"}'