Regenerate the identity's single-use recovery codes
/v1/identity/auth/mfa/recovery-codes/regenerateAuthentication
- Bearer Token
AuthorizationJWT access token
Headers
x-mfa-step-up-tokenrequired
Code samples
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"
const response = await fetch("https://api.canopy.dev/v1/identity/auth/mfa/recovery-codes/regenerate", {
method: "POST",
headers: {
"x-mfa-step-up-token": "value",
"Authorization": "Bearer $CANOPY_TOKEN"
},
});
const data = await response.json();import requests
response = requests.post(
"https://api.canopy.dev/v1/identity/auth/mfa/recovery-codes/regenerate",
headers={
"x-mfa-step-up-token": "value",
"Authorization": "Bearer $CANOPY_TOKEN"
},
)
data = response.json()package main
import (
"net/http"
)
func main() {
req, _ := http.NewRequest("POST", "https://api.canopy.dev/v1/identity/auth/mfa/recovery-codes/regenerate", nil)
req.Header.Set("x-mfa-step-up-token", "value")
req.Header.Set("Authorization", "Bearer $CANOPY_TOKEN")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
}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_codes *string[]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_generation *numberMonotonically-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)