Password recovery

Password recovery is public but rate-limited. Responses should not be used to determine whether an account exists.

1. Create a code challenge

POST /api/v1/authentication/recovery/code-challenges

{
  "identifier": "user@example.com",
  "channel": "EMAIL",
  "locale": "fa"
}

Supported notification locales are English, Persian/Dari, and Pashto. The request locale header takes precedence when present.

POST /api/v1/authentication/recovery/code-verifications

{
  "identifier": "user@example.com",
  "channel": "EMAIL",
  "code": "123456"
}

A successful verification returns a short-lived recovery token.

POST /api/v1/authentication/recovery/password-resets

{
  "recovery_token": "RECOVERY_TOKEN",
  "new_password": "a-new-password",
  "revoke_sessions": true
}

Passwords must contain at least eight characters. Prefer revoke_sessions: true after suspected compromise.