Skip to main content

Documentation Index

Fetch the complete documentation index at: https://alphabet-06152314.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

These endpoints manage multi-factor authentication enrollment and the MFA login challenge flow. All endpoints except POST /api/v1/auth/mfa/login operate on an already-authenticated session and require a valid bearer token. The MFA login endpoint is the second step in a two-phase sign-in sequence and does not require prior authentication.
MFA enrollment is a two-step process: first call the enable-* endpoint to generate setup details, then call the corresponding verify-* endpoint with a valid code to activate MFA on the account and receive recovery codes.

​
POST /api/v1/auth/mfa/enable-authenticator

Begins authenticator-app enrollment. The server generates a TOTP secret and returns the data you need to configure an authenticator application such as Google Authenticator or 1Password. Authorization: Bearer <accessToken> required No request body.

​
Responses

200 OK — AuthenticatorSetupDto
​
authenticatorUri
string
An otpauth:// URI that encodes the secret. Pass this to a QR code library to display a scannable code to the user.
​
manualEntryKey
string
The raw base-32 secret key. Provide this to users who cannot scan the QR code and need to enter the secret manually.
400 Bad Request — ProblemDetails — Enrollment setup failed.

​
POST /api/v1/auth/mfa/verify-authenticator

Completes authenticator-app enrollment by validating a TOTP code generated by the user’s authenticator app. On success, MFA is activated on the account and a set of recovery codes is returned. Authorization: Bearer <accessToken> required

​
Request body

​
verificationCode
string
required
The 6-digit code currently displayed in the authenticator app.

​
Responses

200 OK — RecoveryCodesDto
​
codes
string[]
A list of single-use recovery codes. Store these securely — they cannot be retrieved again. Each code can be used in place of a TOTP code if the user loses access to their authenticator app.
400 Bad Request — ProblemDetails — Verification failed. The code may be incorrect or expired.
Display the recovery codes to the user immediately and instruct them to save the codes in a secure location. Once this response is dismissed, the codes cannot be retrieved — only regenerated (which invalidates the old set).

​
POST /api/v1/auth/mfa/enable-otp

Enables OTP-based MFA delivery for the authenticated user through a supported channel (e.g., SMS or email). Authorization: Bearer <accessToken> required

​
Request body

​
channel
string
required
The delivery channel for the OTP. Accepted values depend on your server configuration (e.g., "sms", "email").

​
Responses

200 OK — OTP delivery configured. Proceed to POST /api/v1/auth/mfa/verify-otp with the code sent to the user. 400 Bad Request — ProblemDetails — OTP setup failed (e.g., unsupported channel).

​
POST /api/v1/auth/mfa/verify-otp

Validates the OTP code sent to the user via the configured channel and confirms the OTP MFA method on the account. Authorization: Bearer <accessToken> required

​
Request body

​
code
string
required
The one-time password received on the configured delivery channel.

​
Responses

200 OK — OTP verified. OTP-based MFA is now active on the account. 400 Bad Request — ProblemDetails — Verification failed. The code may be incorrect or expired.

​
POST /api/v1/auth/mfa/login

Completes a two-phase MFA login. Call this endpoint after receiving an mfaToken from POST /api/v1/auth/login. Submitting a valid mfaToken and verificationCode issues the final access and refresh tokens. Authorization: None required

​
Request body

​
mfaToken
string
required
The temporary MFA token returned by POST /api/v1/auth/login when the account has MFA enabled.
​
verificationCode
string
required
The current TOTP code from the authenticator app, the OTP received on the configured channel, or a recovery code.
​
useCookies
boolean
default:"false"
When true, the access and refresh tokens are also written to the response as HttpOnly cookies.

​
Responses

200 OK — AuthResponseDto
​
accessToken
string
A signed JWT access token. Include this in the Authorization: Bearer header for subsequent authenticated requests.
​
refreshToken
string
A refresh token for obtaining new token pairs without re-authenticating. See POST /api/v1/auth/refresh-token.
400 Bad Request — ProblemDetails — MFA login failed. The mfaToken may be expired or the verificationCode may be incorrect.

​
Example

curl -X POST https://localhost:5001/api/v1/auth/mfa/login \
  -H "Content-Type: application/json" \
  -d '{
    "mfaToken": "<mfa-token-from-login>",
    "verificationCode": "123456",
    "useCookies": false
  }'

​
GET /api/v1/auth/mfa/recovery-codes

Returns the currently active recovery codes for the authenticated user. Use this endpoint to let users view their codes after initial enrollment. Authorization: Bearer <accessToken> required No request body.

​
Responses

200 OK — RecoveryCodesDto
​
codes
string[]
The list of remaining single-use recovery codes.
400 Bad Request — ProblemDetails — Could not retrieve recovery codes.

​
POST /api/v1/auth/mfa/recovery-codes/regenerate

Generates a fresh set of recovery codes and immediately invalidates all previously issued codes. Use this if the user suspects their recovery codes have been compromised. Authorization: Bearer <accessToken> required No request body.

​
Responses

200 OK — RecoveryCodesDto
​
codes
string[]
The newly generated recovery codes. All previous codes are now invalid.
400 Bad Request — ProblemDetails — Regeneration failed.
Calling this endpoint immediately invalidates all existing recovery codes. Ensure the user saves the new codes before navigating away.