# Benutzer auflisten

`GET /v1/users` · Berechtigung `users:read`

Listet die Benutzer der Umgebung mit Cursor-Paginierung auf, standardmäßig die neuesten zuerst. Hier werden nur Filter akzeptiert, die keine personenbezogenen Daten enthalten. Um Benutzer anhand von E-Mail-Adresse, Telefonnummer oder Benutzername zu suchen, verwenden Sie [Benutzer suchen](/docs/api/management/users/search).

## Anfrage

| 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`. |
| `status` | query | nein | `active`, `blocked` oder `pending_deletion`. |
| `external_id` | query | nein | Exakte Übereinstimmung mit Ihrer eigenen Kennung. |
| `created_after` | query | nein | RFC-3339-Zeitpunkt; Benutzer, die danach erstellt wurden. |
| `created_before` | query | nein | RFC-3339-Zeitpunkt; Benutzer, die davor erstellt wurden. |

Ein Cursor ist nur mit denselben Filtern und derselben Reihenfolge gültig, für die er ausgestellt wurde; andernfalls schlägt die Anfrage mit `invalid_cursor` fehl.

## Antwort

`200 OK`. `data` enthält die Benutzer auf der Seite; `list_metadata.before` und `list_metadata.after` sind Cursor für die vorherige bzw. nächste Seite (`null`, wenn keine vorhanden ist). Eine Gesamtanzahl wird nicht 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.

```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 | `invalid_cursor` | Der Cursor ist fehlerhaft, manipuliert oder wurde für andere Filter ausgestellt. |
| 422 | `validation_failed` | Ein Query-Parameter ist ungültig (`limit` außerhalb des Bereichs, ungültiger Zeitstempel, wiederholter Parameter). |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt 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 "https://api.eu.keenauth.com/v1/users?limit=20&status=active" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

## Personenbezogene Daten

Dieser Endpunkt enthält personenbezogene Daten: Profil von Endnutzern. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) beschreibt, welche Daten gespeichert werden, wie lange sie aufbewahrt und wie sie gelöscht werden. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).