Recupera lo stato di accesso di un utente

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

Restituisce ciò che il tuo team di supporto ti serve quando un utente non riesce ad accedere: i blocchi dell'account aperti, i conteggi dei tentativi falliti ancora attivi su ciascun percorso di accesso e l'ultima autenticazione riuscita. La chiamata è di sola lettura; non modifica nulla e non scrive alcun record di audit. Per rimuovere i blocchi, usa POST /v1/users/{user_id}:unlock.

La risposta non include mai l'identificativo interno del soggetto del contatore, un indirizzo email, un indirizzo IP, un dispositivo o un ID di sessione. Per le sessioni dell'utente, usa GET /v1/users/{user_id}/sessions.

Ambito organizzazione

Passa org_id per ottenere una vista diagnostica dei membri per un admin dell'organizzazione. La chiave deve avere anche l'autorizzazione organizations:read; senza di essa la richiesta fallisce con 403 insufficient_permissions prima che venga letto qualcosa. Se l'utente non è membro di quell'organizzazione (nessuna appartenenza invited, active o suspended), la richiesta fallisce con 404 not_found, la stessa risposta data per un utente sconosciuto. Se l'utente è membro, last_sign_in proviene solo dalle sessioni nel contesto di quell'organizzazione, e failures è sempre un array vuoto, perché i contatori dei tentativi falliti non sono attribuiti ad alcuna organizzazione. I blocchi vengono comunque restituiti, dato che un blocco interrompe l'accesso dell'account in ogni contesto. Senza org_id la risposta resta invariata.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path sì ID utente, con prefisso usr_.
org_id query no ID organizzazione, con prefisso org_. Limita la vista a quell'organizzazione; vedi Ambito organizzazione. Richiede organizations:read.

Risposta

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"}
}
Campo Descrizione
locked true quando almeno un percorso di accesso è bloccato.
locked_until Quando termina l'ultimo blocco aperto; null senza blocchi.
locks Blocchi aperti, dal più vecchio, al massimo uno per percorso (password, totp, sms_2fa, email_2fa, otp, recovery_code).
failures Tentativi falliti dall'ultimo successo o dall'ultimo blocco, per percorso, mentre la finestra di conteggio è attiva. Dopo window_ends_at il conteggio riparte da zero. La finestra per la password è brute_force.window_minutes dell'ambiente.
last_sign_in L'autenticazione riuscita più recente tra le sessioni ancora conservate: authenticated_at (una riautenticazione nella stessa sessione la sposta in avanti), i metodi di autenticazione (amr, RFC 8176) e l'ultimo paese noto della sessione (null se sconosciuto). null quando non è conservata alcuna sessione: l'utente non ha mai effettuato l'accesso, oppure l'ultima sessione è terminata più di 30 giorni fa.

Errori

Ogni errore è un corpo application/problem+json con un code stabile.

HTTP code Quando
404 not_found L'utente non esiste in questo ambiente (o l'ID è malformato), oppure è stato passato org_id e l'utente non è membro di quell'organizzazione.
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:read, oppure è stato passato org_id e la chiave non ha organizations:read.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza non è disponibile temporaneamente; riprova più tardi.

Esempio

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