Elenca utenti

GET /v1/users · autorizzazione users:read

Elenca gli utenti dell'ambiente con paginazione a cursore, dal più recente per impostazione predefinita. Qui sono accettati solo filtri che non contengono dati personali. Per cercare utenti per indirizzo email, numero di telefono o username usa Cerca utenti.

Richiesta

Parametro In Obbligatorio Descrizione
limit query no Dimensione della pagina, da 1 a 100. Predefinito 20.
after query no Cursore opaco da list_metadata.after. Esclusivo con before.
before query no Cursore opaco da list_metadata.before. Esclusivo con after.
order query no asc o desc per data di creazione. Predefinito desc.
status query no active, blocked o pending_deletion.
external_id query no Corrispondenza esatta con il tuo identificatore.
created_after query no Orario RFC 3339; utenti creati dopo di esso.
created_before query no Orario RFC 3339; utenti creati prima di esso.

Un cursore è valido solo con gli stessi filtri e lo stesso ordine per cui è stato emesso; altrimenti la richiesta fallisce con invalid_cursor.

Risposta

200 OK. data contiene gli utenti della pagina; list_metadata.before e list_metadata.after sono i cursori per la pagina precedente e successiva (null quando non c'è). Non viene restituito alcun conteggio totale.

I dati personali sono mascherati quando la chiave non ha l'autorizzazione users:read_pii: email diventa a***@e***.com, phone_number conserva solo le ultime 2 cifre (+**********67), name, given_name, family_name, middle_name e nickname diventano iniziali (A. L.), username conserva solo il primo carattere (a***), birthdate diventa ****-**-** e address diventa {"redacted": true}. user_metadata e app_metadata non sono mascherati.

{
  "data": [ {
    "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
  } ],
  "list_metadata": { "before": null, "after": "<opaque cursor>" }
}

Errori

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

HTTP code Quando
400 invalid_cursor Il cursore è malformato, manomesso o è stato emesso per altri filtri.
422 validation_failed Un parametro di query non è valido (limit fuori intervallo, timestamp errato, parametro ripetuto).
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:read.
429 rate_limited È stato superato il limite di frequenza; rispetta Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile; riprova più tardi.

Esempio

curl "https://api.eu.keenauth.com/v1/users?limit=20&status=active" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Dati personali

Questo endpoint contiene dati personali: profilo dell'utente finale. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.