v1auth contextCredential management
Recovery codes
POST /v1/auth/credentials/recovery-codes — generating single-use fallback sign-in codes.
Recovery codes are the last lifeline for "every primary credential is gone": the device was lost, the authenticator was deleted, the passkey lives on a machine that broke. They must be copyable once, and they must never be readable again.
Request
| Parameter | Type | Required | Notes |
|---|---|---|---|
count | number | Optional | Number of codes, 6–20; the server decides when omitted |
{
"success": true,
"codes": ["a1b2-c3d4-e5f6", "g7h8-i9j0-k1l2"],
"credential": { "id": "cred_...", "type": "recovery_code" }
}Rules
| Rule | Notes |
|---|---|
| Plaintext appears once | codes is returned in this response only; the store keeps hashes |
| Regenerating invalidates the old set | Generating a new set immediately kills the previous one |
| Single use | Each code is removed from the set once used |
| Step-up | max_age=300 |
| Audit | Only the count is recorded, never the codes |
Why the codes are not in the audit log
Writing recovery codes into an audit table copies backup sign-in credentials into a place with weaker protection. The count is enough: the question to answer is "when was a new set generated", not "what were those codes".
Related
- Signing in with a recovery code: Verification challenges
- Other credential types: Credential management