# Einen Benutzer sperren

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

Sperrt einen Benutzer mit einer Kundensperre (`source = admin_api`); der Status wird `blocked`. Das Sperren eines bereits gesperrten Benutzers gelingt, ohne dass sich etwas ändert. Ein Benutzer, dessen Löschung aussteht, kann nicht gesperrt werden. Das Widerrufen der Sitzungen des Benutzers läuft asynchron. Senden Sie einen `Idempotency-Key`-Header, damit Wiederholungen sicher sind.

## Anfrage

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

Optionaler Body:

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `note` | string | nein | Bis zu 1000 Zeichen. Schreiben Sie keine personenbezogenen Daten hinein. |

## Antwort

`200 OK`. Der Body ist das Benutzerobjekt. Der `ETag`-Header enthält die Version des Benutzers.

Personenbezogene Daten werden maskiert, wenn dem Schlüssel die Berechtigung `users:read_pii` fehlt: `email` wird zu `a***@e***.com`, `phone_number` behält nur die letzten 2 Ziffern (`+**********67`), `name`, `given_name`, `family_name`, `middle_name` und `nickname` werden zu Initialen (`A. L.`), `username` behält nur das erste Zeichen (`a***`), `birthdate` wird zu `****-**-**` und `address` wird zu `{"redacted": true}`. `user_metadata` und `app_metadata` werden nicht maskiert.

```json
{
  "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
  "kind": "regular",
  "status": "active",
  "external_id": null,
  "username": null,
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "email_verified": true,
  "phone_number": null,
  "phone_verified": false,
  "user_metadata": {},
  "app_metadata": {},
  "created_via": "admin_api",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "last_sign_in_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null
}
```

## 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. |
| 409 | `conflict` | Der Benutzer wartet auf seine Löschung (`errors[].code` ist `user_pending_deletion`). |
| 415 | `unsupported_media_type` | Ein Body wurde ohne `Content-Type: application/json` gesendet. |
| 422 | `validation_failed` | `note` ist zu lang. |
| 404 | `not_found` | Der Benutzer existiert in dieser Umgebung nicht (oder die ID ist fehlerhaft). |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt die Berechtigung `users:write`. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut. |

## Beispiel

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p:block \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note": "Suspected account takeover"}'
```

## Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Endnutzerprofil. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).