Cerca utenti

POST /v1/users:search · autorizzazione users:read

Cerca utenti con filtri che contengono dati personali. Questi filtri sono accettati solo nel corpo della richiesta, mai nella query string, perché le query string finiscono nei log di proxy e client. I filtri si combinano con AND e serve almeno un filtro di identità. Le corrispondenze sono esatte; la ricerca per prefisso e per sottostringa non è offerta. Una ricerca che corrisponde a troppi utenti fallisce con search_too_broad; restringi i filtri.

Richiesta

I parametri di paginazione vanno nella query string; non contengono dati personali.

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.

Campi del corpo:

Campo Tipo Obbligatorio Descrizione
email string no Indirizzo email esatto.
phone string no Numero di telefono esatto in formato E.164.
username string no Username esatto.
email_domain string no Dominio email esatto.
app_metadata, user_metadata object no Fino a 3 chiavi di primo livello; ogni chiave deve corrispondere a un valore scalare.
status string no active, blocked o pending_deletion.

Un cursore è valido solo con lo stesso insieme di filtri e lo stesso ordine per cui è stato emesso.

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 se non ce n'è una). 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 mantiene solo le ultime 2 cifre (+**********67), name, given_name, family_name, middle_name e nickname diventano iniziali (A. L.), username mantiene solo il primo carattere (a***), birthdate diventa ****-**-** e address diventa {"redacted": true}. user_metadata e app_metadata non sono mascherati. Una chiave senza users:read_pii può comunque cercare con filtri esatti sui dati personali; i risultati 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 unknown_field, invalid_cursor Il corpo contiene un campo non supportato (ad esempio un filtro per prefisso), oppure il cursore non corrisponde alla richiesta.
415 unsupported_media_type Content-Type non è application/json.
422 validation_failed, search_too_broad Un filtro non è valido, non è stato dato alcun filtro di identità, oppure la ricerca corrisponde a troppi utenti.
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 -X POST "https://api.eu.keenauth.com/v1/users:search?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'

Dati personali

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