POST /v1/auth/mfa/recovery-codes

Regenerate the user's MFA recovery codes. Returns a fresh batch of 10 codes and invalidates the previous batch.

::: tip Auth Required: cookie or Bearer. Body must include current password. :::

Request

POST /v1/auth/mfa/recovery-codes

Header	Required	Notes
Cookie: identsphere_at=... OR Authorization: Bearer ...	yes	—
Content-Type: application/json	yes	—

Body

{ "password": "correct-horse-battery-staple" }

Response

200 OK

{
  "recovery_codes": [
    "Yj7nKp2qA8",
    "M4xRv9bC1z",
    "Q3wPe5sL8h",
    "T6yUu2iR4o",
    "B7nMx5cV1z",
    "L8kJh4gF2d",
    "S3aQ5wE9rT",
    "F2dG3hY4uI",
    "Z1xC4vB7nM",
    "P9oL5kJ8hG"
  ]
}

::: warning Show exactly once The plaintext codes are returned here and never again. Display them and remind the user to store them somewhere safe (password manager, etc.). :::

Error responses

Status	Code	When
400	invalid_input	Password missing.
401	authentication_required	Password doesn't match.
403	forbidden	MFA is not enabled — there's nothing to regenerate.
404	not_found	User no longer exists.

Example: curl

curl -X POST https://auth.example.com/v1/auth/mfa/recovery-codes \
  -H 'Content-Type: application/json' \
  -b cookies.txt \
  -d '{"password":"correct-horse-battery-staple"}'

Notes

• The prior batch is deleted before the new batch is inserted.
• An audit entry (auth.mfa.recovery_codes_regenerated) is recorded.
• The codes are 10 alphanumeric characters each, generated from a CSPRNG.