# Démarrer la récupération de compte pour un utilisateur

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

Envoie un lien de récupération (valable 24 heures) à l'adresse e-mail principale de l'utilisateur, sans délai d'attente ; c'est le chemin du mode de récupération `admin_only`. La demande est ouverte directement avec le statut `ready`, et une demande de récupération ouverte est remplacée dans la même transaction (`superseded`). Le lien n'est jamais renvoyé. Le corps facultatif sert uniquement à sélectionner la langue de l'e-mail. Envoyez un en-tête `Idempotency-Key` pour que les nouvelles tentatives soient sans risque.

## Requête

| Paramètre | Dans | Obligatoire | Description |
|---|---|---|---|
| `user_id` | path | oui | Identifiant de l'utilisateur, préfixé `usr_`. |

Corps facultatif :

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `locale` | string | non | Étiquette de langue BCP 47 de l'e-mail, par exemple `tr` ou `pt-BR`. Par défaut, la langue de l'utilisateur ou de l'environnement. |

## Réponse

`200 OK`. `request_id` identifie la demande de récupération (préfixe `arq_`) ; `superseded` indique si une demande ouverte a été remplacée.

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

## Erreurs

Chaque erreur est un corps `application/problem+json` contenant un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Le corps n'est pas un JSON valide ou contient un champ inconnu. |
| 409 | `conflict` | La récupération de compte est `disabled` dans les paramètres de l'environnement, ou l'utilisateur n'a pas d'adresse e-mail principale. |
| 415 | `unsupported_media_type` | Un corps a été envoyé sans `Content-Type: application/json`. |
| 422 | `validation_failed` | `locale` n'est pas une étiquette de langue BCP 47 valide, ou un champ a un type incorrect. |
| 404 | `not_found` | L'utilisateur n'existe pas dans cet environnement (ou l'identifiant est mal formé). |
| 401 | `unauthenticated` | La clé API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de l'autorisation `user-credentials:write`. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; respectez `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez plus tard. |

## Exemple

```bash
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"}'
```