# 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.

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

```bash
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](/docs/policies/personal-data) 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).