# Anmeldestatus eines Benutzers abrufen

`GET /v1/users/{user_id}/sign-in-state` · Berechtigung `users:read`

Gibt zurück, was Ihr Support-Team benötigt, wenn sich ein Benutzer nicht anmelden kann: die offenen Kontosperren des Benutzers, die laufenden Fehlversuchszähler für jeden Anmeldepfad und die letzte erfolgreiche Authentifizierung. Der Aufruf liest nur; es wird nichts geändert und kein Auditeintrag geschrieben. Um die Sperren aufzuheben, verwenden Sie [`POST /v1/users/{user_id}:unlock`](unlock.md).

Die Antwort enthält nie die interne Subject-Kennung des Zählers, eine E-Mail-Adresse, eine IP-Adresse, ein Gerät oder eine Sitzungs-ID. Für die Sitzungen des Benutzers verwenden Sie [`GET /v1/users/{user_id}/sessions`](list-sessions.md).

## Organisationsumfang

Übergeben Sie `org_id`, um eine Diagnoseansicht der Mitglieder für einen Organisationsadministrator zu erstellen. Der Schlüssel benötigt dann außerdem die Berechtigung `organizations:read`; ohne sie schlägt die Anfrage mit `403 insufficient_permissions` fehl, bevor etwas gelesen wird. Ist der Benutzer kein Mitglied dieser Organisation (keine Mitgliedschaft mit den Status `invited`, `active` oder `suspended`), schlägt die Anfrage mit `404 not_found` fehl, dieselbe Antwort wie für einen unbekannten Benutzer. Ist der Benutzer Mitglied, stammt `last_sign_in` nur aus Sitzungen im Kontext dieser Organisation, und `failures` ist immer ein leeres Array, weil Fehlversuchszähler keiner Organisation zugeordnet werden. Sperren werden dennoch zurückgegeben, da eine Sperre die Anmeldung des Kontos in jedem Kontext stoppt. Ohne `org_id` bleibt die Antwort unverändert.

## Anfrage

| Parameter | In | Pflichtfeld | Beschreibung |
|---|---|---|---|
| `user_id` | Pfad | ja | Benutzer-ID, mit dem Präfix `usr_`. |
| `org_id` | Query | nein | Organisations-ID, mit dem Präfix `org_`. Beschränkt die Ansicht auf diese Organisation; siehe [Organisationsumfang](#organisationsumfang). Benötigt `organizations:read`. |

## Antwort

`200 OK`.

```json
{
  "locked": true,
  "locked_until": "2026-10-20T10:00:00Z",
  "locks": [
    {"id": "lck_0a1b2c3d4e5f6g7h8j9k0m1n2p", "path": "password",
     "locked_at": "2026-10-20T09:45:00Z", "expires_at": "2026-10-20T10:00:00Z"}
  ],
  "failures": [
    {"path": "totp", "count": 3, "window_ends_at": "2026-10-20T09:55:00Z"}
  ],
  "last_sign_in": {"authenticated_at": "2026-10-19T18:12:04Z", "amr": ["pwd", "otp"], "country": "DE"}
}
```

| Feld | Beschreibung |
|---|---|
| `locked` | `true`, wenn mindestens ein Anmeldepfad gesperrt ist. |
| `locked_until` | Zeitpunkt, an dem die letzte offene Sperre endet; `null` ohne Sperre. |
| `locks` | Offene Sperren, die älteste zuerst, höchstens eine pro Pfad (`password`, `totp`, `sms_2fa`, `email_2fa`, `otp`, `recovery_code`). |
| `failures` | Fehlgeschlagene Versuche seit dem letzten Erfolg oder der letzten Sperre, pro Pfad, während das Zählfenster läuft. Nach `window_ends_at` beginnt die Zählung von vorn. Das Passwortfenster ist der Wert `brute_force.window_minutes` der Umgebung. |
| `last_sign_in` | Die jüngste erfolgreiche Authentifizierung unter den noch gespeicherten Sitzungen: `authenticated_at` (eine erneute Authentifizierung in derselben Sitzung verschiebt den Wert nach vorn), die Authentifizierungsmethoden (`amr`, RFC 8176) und das zuletzt bekannte Land der Sitzung (`null`, wenn unbekannt). `null`, wenn keine Sitzung gespeichert ist: Der Benutzer hat sich nie angemeldet, oder die letzte Sitzung endete vor mehr als 30 Tagen. |

## Fehler

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

| HTTP | `code` | Wann |
|---|---|---|
| 404 | `not_found` | Der Benutzer existiert in dieser Umgebung nicht (oder die ID ist fehlerhaft), oder `org_id` wurde angegeben und der Benutzer ist kein Mitglied dieser Organisation. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt die Berechtigung `users:read`, oder `org_id` wurde angegeben und dem Schlüssel fehlt `organizations:read`. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage später. |

## Beispiel

```bash
curl https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/sign-in-state \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

CLI: `keenauth users sign-in-state usr_0a1b2c3d4e5f6g7h8j9k0m1n2p`