Benutzer suchen

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

Durchsucht Benutzer mit Filtern, die personenbezogene Daten enthalten. Diese Filter werden nur im Anfragetext akzeptiert, niemals in der Abfragezeichenfolge, weil Abfragezeichenfolgen in Proxy- und Client-Protokollen landen. Filter werden mit UND kombiniert, und mindestens ein Identitätsfilter ist erforderlich. Treffer müssen exakt übereinstimmen; Präfix- und Teilstringsuche werden nicht angeboten. Eine Suche, die zu viele Benutzer findet, schlägt mit search_too_broad fehl; grenzen Sie die Filter ein.

Anfrage

Paginierungsparameter werden in der Abfragezeichenfolge übergeben; sie enthalten keine personenbezogenen Daten.

Parameter In Erforderlich Beschreibung
limit query nein Seitengröße, 1 bis 100. Standard 20.
after query nein Undurchsichtiger Cursor aus list_metadata.after. Schließt before aus.
before query nein Undurchsichtiger Cursor aus list_metadata.before. Schließt after aus.
order query nein asc oder desc nach Erstellungszeitpunkt. Standard desc.

Feld im Anfragetext:

Feld Typ Erforderlich Beschreibung
email string nein Exakte E-Mail-Adresse.
phone string nein Exakte Telefonnummer im E.164-Format.
username string nein Exakter Benutzername.
email_domain string nein Exakte E-Mail-Domain.
app_metadata, user_metadata object nein Bis zu 3 Schlüssel auf oberster Ebene; jeder Schlüssel muss einem skalaren Wert entsprechen.
status string nein active, blocked oder pending_deletion.

Ein Cursor ist nur mit derselben Menge an Filtern und derselben Reihenfolge gültig, für die er ausgestellt wurde.

Antwort

200 OK. data enthält die Benutzer der Seite; list_metadata.before und list_metadata.after sind Cursor für die vorherige und die nächste Seite (null, wenn keine vorhanden ist). Es wird keine Gesamtanzahl zurückgegeben.

Personenbezogene Daten werden maskiert, wenn der Schlüssel die Berechtigung users:read_pii nicht besitzt: email wird zu a***@e***.com, phone_number behält nur die letzten 2 Ziffern (+**********67), name, given_name, family_name, middle_name und nickname werden zu Initialen (A. L.), username behält nur das erste Zeichen (a***), birthdate wird zu ****-**-** und address wird zu {"redacted": true}. user_metadata und app_metadata werden nicht maskiert. Ein Schlüssel ohne users:read_pii kann dennoch mit exakten Filtern für personenbezogene Daten suchen; die Ergebnisse sind maskiert.

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

Fehler

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

HTTP code Wann
400 unknown_field, invalid_cursor Der Body enthält ein nicht unterstütztes Feld (zum Beispiel einen Präfixfilter) oder der Cursor passt nicht zur Anfrage.
415 unsupported_media_type Content-Type ist nicht application/json.
422 validation_failed, search_too_broad Ein Filter ist ungültig, es wurde kein Identitätsfilter angegeben oder die Suche trifft zu viele Benutzer.
401 unauthenticated Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen.
403 insufficient_permissions Der Schlüssel besitzt nicht die Berechtigung users:read.
429 rate_limited Das Ratenlimit wurde überschritten; beachten Sie Retry-After.
503 service_unavailable Eine Abhängigkeit ist vorübergehend nicht verfügbar; versuchen Sie es später erneut.

Beispiel

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"}'

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Endnutzerprofil. Personenbezogene Daten in den KeenAuth-APIs beschreibt, welche Daten gespeichert werden, wie lange sie aufbewahrt werden und wie sie gelöscht werden. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).