# Sitzungen eines Benutzers widerrufen

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

Widerruft die Sitzungen des Benutzers und die an sie gebundenen Refresh-Token-Familien; Access-Token, die daraus ausgestellt wurden, werden von Introspection und der Widerrufsprüfung nicht mehr akzeptiert. Ohne Body (oder mit `{}`) wird jede Sitzung des Benutzers widerrufen. Höchstens ein Filter darf angegeben werden:

- `session_id`: nur diese Sitzung (sie muss dem Benutzer gehören, sonst `404`).
- `org_id`: die Sitzungen, die im Kontext dieser Organisation geöffnet wurden, und die Refresh-Token-Familien des Benutzers für diese Organisation.
- `client_id`: nur die Refresh-Token-Familien dieser Anwendung für diesen Benutzer; die Sitzungen bleiben offen. Verwenden Sie die Anwendungs-ID (`app_…`); die URL-Form der `client_id` einer Anwendung mit Client ID Metadata Document wird nicht akzeptiert.

Bereits widerrufene oder abgelaufene Sitzungen werden nicht mitgezählt; ein wiederholter Aufruf gelingt daher mit Anzahl null. Jeder Widerruf wird im Verwaltungs-Audit-Log protokolliert. Senden Sie einen `Idempotency-Key`-Header, damit Wiederholungen sicher sind.

## Anfrage

| Parameter | In | Erforderlich | Beschreibung |
|---|---|---|---|
| `user_id` | path | ja | Benutzer-ID mit Präfix `usr_`. |

Optionaler Body (höchstens ein Feld):

| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
| `session_id` | string | nein | Sitzungs-ID mit Präfix `ses_`. |
| `org_id` | string | nein | Organisations-ID mit Präfix `org_`. |
| `client_id` | string | nein | Anwendungs-ID mit Präfix `app_`. |

## Antwort

`200 OK`.

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

`revoked_sessions` ist bei `client_id` `0` (die Sitzungen bleiben offen).

## Fehler

Jeder Fehler ist ein `application/problem+json`-Body mit einem stabilen `code`.

| HTTP | `code` | Wann |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Der Body ist kein gültiges JSON oder enthält ein unbekanntes Feld. |
| 415 | `unsupported_media_type` | Ein Body wurde ohne `Content-Type: application/json` gesendet. |
| 422 | `validation_failed` | Mehr als ein Filter (`mutually_exclusive`), eine fehlerhafte ID (`invalid_value`), oder die Organisation bzw. Anwendung existiert in dieser Umgebung nicht (`not_found` bei `/org_id` oder `/client_id`). |
| 404 | `not_found` | Der Benutzer existiert in dieser Umgebung nicht, oder `session_id` ist keine Sitzung des Benutzers. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt die Berechtigung `sessions:write`. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; später erneut versuchen. |

## Beispiel

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