# Revocar las sesiones de un usuario

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

Revoca las sesiones del usuario y las familias de refresh tokens vinculadas a ellas; los access tokens que emitieron dejan de aceptarse en la introspección y en la comprobación de revocación. Sin cuerpo (o con `{}`) se revocan todas las sesiones del usuario. Puede indicarse como máximo un filtro:

- `session_id`: solo esa sesión (debe pertenecer al usuario; de lo contrario, `404`).
- `org_id`: las sesiones abiertas en el contexto de esa organización y las familias de refresh tokens del usuario para esa organización.
- `client_id`: solo las familias de refresh tokens de esa aplicación para este usuario; las sesiones permanecen abiertas. Use el id de la aplicación (`app_…`); no se acepta el `client_id` en forma de URL de una aplicación con Documento de Metadatos de ID de Cliente.

Las sesiones que ya están revocadas o expiradas no se cuentan, así que una llamada repetida tiene éxito con recuentos en cero. Cada revocación se registra en el registro de auditoría de gestión. Envíe una cabecera `Idempotency-Key` para que los reintentos sean seguros.

## Solicitud

| Parámetro | En | Obligatorio | Descripción |
|---|---|---|---|
| `user_id` | path | sí | Id de usuario, con el prefijo `usr_`. |

Cuerpo opcional (como máximo un campo):

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `session_id` | string | no | Id de sesión, con el prefijo `ses_`. |
| `org_id` | string | no | Id de organización, con el prefijo `org_`. |
| `client_id` | string | no | Id de aplicación, con el prefijo `app_`. |

## Respuesta

`200 OK`.

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

`revoked_sessions` es `0` con `client_id` (las sesiones permanecen abiertas).

## Errores

Cada error es un cuerpo `application/problem+json` con un `code` estable.

| HTTP | `code` | Cuándo |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | El cuerpo no es JSON válido o tiene un campo desconocido. |
| 415 | `unsupported_media_type` | Se envió un cuerpo sin `Content-Type: application/json`. |
| 422 | `validation_failed` | Más de un filtro (`mutually_exclusive`), un id mal formado (`invalid_value`), o la organización o la aplicación no existe en este entorno (`not_found` en `/org_id` o `/client_id`). |
| 404 | `not_found` | El usuario no existe en este entorno, o `session_id` no es una de las sesiones del usuario. |
| 401 | `unauthenticated` | Falta la clave de API, no es válida o está revocada. |
| 403 | `insufficient_permissions` | La clave no tiene el permiso `sessions:write`. |
| 429 | `rate_limited` | Se superó el límite de frecuencia; respete `Retry-After`. |
| 503 | `service_unavailable` | Una dependencia no está disponible temporalmente; reintente más tarde. |

## Ejemplo

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