Start account recovery for a user

POST /v1/users/{user_id}:start-recovery · permission user-credentials:write

Sends a recovery link (valid for 24 hours) to the user's primary email without a waiting period; this is the path of the admin_only recovery mode. The request opens directly as ready, and an open recovery request is replaced in the same transaction (superseded). The link is never returned. The optional body only selects the email language. Send an Idempotency-Key header to make retries safe.

Request

Parameter In Required Description
user_id path yes User id, prefixed usr_.

Optional body:

Field Type Required Description
locale string no BCP 47 language tag of the email, for example tr or pt-BR. Defaults to the user's or the environment's language.

Response

200 OK. request_id identifies the recovery request (prefix arq_); superseded tells whether an open request was replaced.

{
  "request_id": "arq_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "expires_at": "2026-01-16T09:30:00Z",
  "superseded": false
}

Errors

Every error is an application/problem+json body with a stable code.

HTTP code When
400 malformed_request, unknown_field The body is not valid JSON or has an unknown field.
409 conflict Account recovery is disabled in the environment settings, or the user has no primary email.
415 unsupported_media_type A body was sent without Content-Type: application/json.
422 validation_failed locale is not a valid BCP 47 language tag, or a field has the wrong type.
404 not_found The user does not exist in this environment (or the id is malformed).
401 unauthenticated The API key is missing, invalid or revoked.
403 insufficient_permissions The key lacks the user-credentials:write permission.
429 rate_limited The rate limit was exceeded; honor Retry-After.
503 service_unavailable A dependency is temporarily unavailable; retry later.

Example

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p:start-recovery \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"locale": "en"}'