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.

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.

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. Benötigt organizations:read.

Antwort

200 OK.

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

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