Verify MFA recovery code

POST/auth/mfa/verify-recovery-code

Redeem a single-use recovery (backup) code to COMPLETE the sign-in. Unlike reset-totp, MFA stays enabled and the enrolled factors are untouched — the code acts as a backup authenticator. Returns a full session; the now-verified session can re-enrol a new authenticator via setup-totp inline.

Request body

NestAuthVerifyRecoveryCodeRequestDto

Field	Type	Required	Description
`code`	`string`	required	A single-use MFA recovery (backup) code Example: `aZ8xK2m9Qp`
`trustDevice`	`boolean`	optional	Whether to trust this device for future logins Example: `true`

Examples

Example

{
  "code": "aZ8xK2m9Qp",
  "trustDevice": true
}

Responses

200Header mode: message + tokens in body

Verify2faWithTokensResponseDto

Field	Type	Required	Description
`accessToken`	`string`	required	JWT access token (short-lived) Example: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5…`
`refreshToken`	`string`	required	JWT refresh token (long-lived) Example: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVz…`
`message`	`string`	optional	Verification success message (added by controller) Example: `2FA verification successful`
`user`	`object`	optional	User information with roles and permissions

Example response

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJpYXQiOjE2OTk5OTk5OTksImV4cCI6MTY5OTk5OTk5OX0.xyz",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiIxMjMiLCJ0eXBlIjoicmVmcmVzaCIsImlhdCI6MTY5OTk5OTk5OX0.abc",
  "message": "2FA verification successful"
}

400Validation failed (bad input).

ApiErrorResponseDto

Field	Type	Required	Description
`statusCode`	`number`	required	HTTP status code Example: `401`
`error`	`string`	required	HTTP status text / exception name Example: `Unauthorized`
`message`	`string`	required	Human-readable message Example: `Invalid credentials`
`code`	`string`	required	Stable, machine-readable error code — branch on this, not the message Example: `INVALID_CREDENTIALS`

Example response

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

401Missing, invalid, or expired authentication.

ApiErrorResponseDto

Field	Type	Required	Description
`statusCode`	`number`	required	HTTP status code Example: `401`
`error`	`string`	required	HTTP status text / exception name Example: `Unauthorized`
`message`	`string`	required	Human-readable message Example: `Invalid credentials`
`code`	`string`	required	Stable, machine-readable error code — branch on this, not the message Example: `INVALID_CREDENTIALS`

Example response

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid credentials",
  "code": "INVALID_CREDENTIALS"
}

Try it

curl -X POST 'https://api.example.com/auth/mfa/verify-recovery-code' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{"code":"aZ8xK2m9Qp","trustDevice":true}'

POST /auth/mfa/verify-recovery-code

Verify MFA recovery code

Request body

Responses

Try it

On this page