Auth Mfa API

12 endpoints in this group.

POST /api/auth/mfa/backup-codes/regenerate

Regenerate Backup Codes

Request body: application/json

Responses

POST /api/auth/mfa/challenge

Mfa Challenge

Trade an mfa-pending token + second-factor code for a full JWT. Called from the frontend after the initial password login returns {mfa_required: true, mfa_token}.

Request body: application/json

Responses

GET /api/auth/mfa/methods

Mfa Methods

Responses

POST /api/auth/mfa/reset/confirm

Mfa Reset Confirm

Public — consume a mfa-reset JWT and clear the user's 2FA enrollment.

Single-use enforcement: the token's jti (or a sha256 of the token when no jti claim is present) is written to mfa_reset_tokens_used on first consumption. A second call with the same token returns 410 Gone.

Request body: application/json

Responses

POST /api/auth/mfa/reset/request

Mfa Reset Request

Authenticated — issue a signed reset token and email it to the user.

Rate-limited at the app layer (see core/rate_limit.py::mfa_reset_rate_limit); we apply it via the route decorator below.

Responses

POST /api/auth/mfa/sms/setup

Sms Setup

Request body: application/json

Responses

POST /api/auth/mfa/sms/verify

Sms Verify

Request body: application/json

Responses

POST /api/auth/mfa/totp/setup

Totp Setup

Responses

POST /api/auth/mfa/totp/verify

Totp Verify

When first-factor enrollment completes, browser-origin calls receive the bp_token cookie. Token API callers receive access_token in the JSON body. The same rule applies to SMS enrollment and MFA challenge completion.

Request body: application/json

Responses

GET /api/auth/mfa/trusted-devices

List Trusted Devices

List active trusted devices for the authenticated user.

Responses

DELETE /api/auth/mfa/trusted-devices/{device_id}

Revoke Trusted Device

Revoke a single trusted device and audit the event.

Parameters

Responses

DELETE /api/auth/mfa/{method}

Delete Method

Parameters

Request body: application/json

Responses