# Revoca le sessioni di un utente

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

Revoca le sessioni dell'utente e le famiglie di refresh token a esse associate; i token di accesso da esse emessi smettono di essere accettati dall'introspezione e dal controllo di revoca. Senza corpo (o con `{}`) viene revocata ogni sessione dell'utente. È possibile indicare al massimo un filtro:

- `session_id`: solo quella sessione (deve appartenere all'utente, altrimenti `404`).
- `org_id`: le sessioni aperte nel contesto di quell'organizzazione e le famiglie di refresh token dell'utente per quell'organizzazione.
- `client_id`: solo le famiglie di refresh token di quell'applicazione per questo utente; le sessioni restano aperte. Usare l'ID applicazione (`app_…`); non è accettato il `client_id` in forma di URL di un'applicazione con Client ID Metadata Document.

Le sessioni già revocate o scadute non vengono conteggiate, quindi una chiamata ripetuta ha successo con conteggi pari a zero. Ogni revoca viene scritta nel log di audit di gestione. Inviare un'intestazione `Idempotency-Key` per rendere sicuri i nuovi tentativi.

## Richiesta

| Parametro | In | Obbligatorio | Descrizione |
|---|---|---|---|
| `user_id` | path | sì | ID utente, con prefisso `usr_`. |

Corpo facoltativo (al massimo un campo):

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `session_id` | string | no | ID sessione, con prefisso `ses_`. |
| `org_id` | string | no | ID organizzazione, con prefisso `org_`. |
| `client_id` | string | no | ID applicazione, con prefisso `app_`. |

## Risposta

`200 OK`.

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

`revoked_sessions` è `0` con `client_id` (le sessioni restano aperte).

## Errori

Ogni errore è un body `application/problem+json` con un `code` stabile.

| HTTP | `code` | Quando |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Il corpo non è JSON valido oppure contiene un campo sconosciuto. |
| 415 | `unsupported_media_type` | Il corpo è stato inviato senza `Content-Type: application/json`. |
| 422 | `validation_failed` | Più di un filtro (`mutually_exclusive`), un ID malformato (`invalid_value`), oppure l'organizzazione o l'applicazione non esiste in questo ambiente (`not_found` su `/org_id` o `/client_id`). |
| 404 | `not_found` | L'utente non esiste in questo ambiente, oppure `session_id` non è una delle sessioni dell'utente. |
| 401 | `unauthenticated` | La chiave API manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La chiave non ha il permesso `sessions:write`. |
| 429 | `rate_limited` | È stato superato il limite di frequenza; attendi il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova più tardi. |

## Esempio

```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`