1. Docs
  2. API Reference
  3. Regenerate the identity's single-use recovery codes

Regenerate the identity's single-use recovery codes

POST/v1/identity/auth/mfa/recovery-codes/regenerate

Authentication

  • Bearer Token Authorization

    JWT access token

Headers

  • x-mfa-step-up-token required

Code samples

cURLJavaScriptPythonGo
curl -X POST "https://api.canopy.dev/v1/identity/auth/mfa/recovery-codes/regenerate" \
  -H "x-mfa-step-up-token: value" \
  -H "Authorization: Bearer $CANOPY_TOKEN"

Responses

200 Mints a fresh batch of 10 codes (incrementing the generation), invalidates every unredeemed code in the prior generation, and returns the new plaintext codes ONCE. Requires step-up. On 401, the body's `error.code` is `mfa.step_up_required` (header missing or invalid) or `auth.invalid_token` (caller's bearer token is invalid).
{
  "recovery_codes": [
    "ABCD-EFGH-IJKL-MNOP",
    "QRST-UVWX-YZ23-4567",
    "..."
  ],
  "recovery_codes_generation": 0
}

application/json

  • recovery_codesstring[]*

    Ten freshly-minted single-use codes. **Shown exactly once** — the prior generation is invalidated in the same call and the server only stores hashes from here on.

  • recovery_codes_generationnumber*

    Monotonically-increasing generation number for this batch. Used by the portal admin surface to show "X of 10 remaining" against the current batch.

401 Invalid or expired token
403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)

Returned object

On this page

Related endpoints

GETList enrolled MFA factors for the caller
POSTBegin TOTP factor enrollment
POSTComplete TOTP factor enrollment
POSTBegin WebAuthn factor enrollment
POSTComplete WebAuthn factor enrollment
POSTProve a fresh factor to authorise a sensitive MFA mutation
POSTBegin a WebAuthn-backed step-up ceremony
POSTComplete a WebAuthn step-up ceremony
DELETERemove an enrolled MFA factor
GETList the identity's active 'remember this device' records
DELETERevoke every trusted device for the caller
DELETERevoke a single trusted device