# Révoquer les sessions d'un utilisateur

`POST /v1/users/{user_id}/sessions:revoke` · autorisation `sessions:write`

Révoque les sessions de l'utilisateur et les familles de jetons d'actualisation qui y sont liées ; les jetons d'accès qu'elles ont émis cessent d'être acceptés par l'introspection et par la vérification de révocation. Sans corps (ou avec `{}`), toutes les sessions de l'utilisateur sont révoquées. Un seul filtre peut être donné au plus :

- `session_id` : seulement cette session (elle doit appartenir à l'utilisateur, sinon `404`).
- `org_id` : les sessions ouvertes dans le contexte de cette organisation et les familles de jetons d'actualisation de l'utilisateur pour cette organisation.
- `client_id` : seulement les familles de jetons d'actualisation de cette application pour cet utilisateur ; les sessions restent ouvertes. Utilisez l'identifiant de l'application (`app_…`) ; la forme URL du `client_id` d'une application à document de métadonnées client (Client ID Metadata Document) n'est pas acceptée.

Les sessions déjà révoquées ou expirées ne sont pas comptées, de sorte qu'un appel répété réussit avec des compteurs à zéro. Chaque révocation est écrite dans le journal d'audit de gestion. Envoyez un en-tête `Idempotency-Key` pour rendre les nouvelles tentatives sûres.

## Demande

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

Corps facultatif (un champ au plus) :

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `session_id` | chaîne | non | Identifiant de session, préfixé `ses_`. |
| `org_id` | chaîne | non | Identifiant d'organisation, préfixé `org_`. |
| `client_id` | chaîne | non | Identifiant d'application, préfixé `app_`. |

## Réponse

`200 OK`.

```json
{
  "revoked_sessions": 2,
  "revoked_token_families": 3
}
```

`revoked_sessions` vaut `0` avec `client_id` (les sessions restent ouvertes).

## Erreurs

Chaque erreur est un corps `application/problem+json` accompagné d'un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Le corps n'est pas du JSON valide ou contient un champ inconnu. |
| 415 | `unsupported_media_type` | Un corps a été envoyé sans `Content-Type: application/json`. |
| 422 | `validation_failed` | Plus d'un filtre (`mutually_exclusive`), un identifiant mal formé (`invalid_value`), ou l'organisation ou l'application n'existe pas dans cet environnement (`not_found` à `/org_id` ou `/client_id`). |
| 404 | `not_found` | L'utilisateur n'existe pas dans cet environnement, ou `session_id` ne fait pas partie des sessions de l'utilisateur. |
| 401 | `unauthenticated` | La clé d'API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne dispose pas de l'autorisation `sessions:write`. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; respectez l'en-tête `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/sessions:revoke \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "org_0a1b2c3d4e5f6g7h8j9k0m1n2p"}'
```

CLI : `keenauth users sessions revoke usr_0a1b2c3d4e5f6g7h8j9k0m1n2p --org-id org_0a1b2c3d4e5f6g7h8j9k0m1n2p --yes`