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.

{
  "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

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