Verzeichnisbenutzer auflisten

GET /v1/directories/{directory_id}/users · Berechtigung directories:read

Listet die aktiven Benutzerdatensätze auf, die der Identitätsanbieter im Verzeichnis bereitgestellt hat, sortiert nach ID: die normalisierten Attribute, die Verzeichnisgruppen des Benutzers, die Verknüpfung mit dem Umgebungsbenutzer und das Abweichungskennzeichen. Gelöschte Datensätze werden nicht zurückgegeben. Die Filter state und group_id können kombiniert werden. Es gibt nur Vorwärtspaginierung; der Cursor ist an das Verzeichnis und die Filter gebunden.

Ohne die Berechtigung users:read_pii erhalten die Anmeldedaten maskierte personenbezogene Daten: user_name als erstes Zeichen und ***, emails[].value als a***@e***.com, given_name, family_name und display_name als Initialen sowie attributes als null. external_id, locale, zoneinfo, die Gruppen und die IDs werden nie maskiert. Ein geheimer Schlüssel besitzt alle Berechtigungen.

Anfrage

Feld Typ Pflicht Beschreibung
directory_id Pfad ja SCIM-Verzeichnis-ID (dir_…).
state Abfrage nein Nur Benutzer in diesem Status: active, inactive oder held (in einer Massen-Deprovisionierungssperre).
group_id Abfrage nein Nur Mitglieder dieser Verzeichnisgruppe (dsg_…); eine Gruppe eines anderen Verzeichnisses liefert eine leere Seite.
limit Abfrage nein 1–100, Standard 20.
after Abfrage nein Der Cursor aus list_metadata.after.

Es gibt keinen Anfragetext.

Antwort

200 OK mit einer Seite von Verzeichnisbenutzern.

{
  "data": [
    {
      "id": "dsu_01j9xp4q6r8s0t2v4w6x8y0z2b",
      "directory_id": "dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
      "external_id": "00u1a2b3c4",
      "user_name": "jane@example.com",
      "emails": [{ "value": "jane@example.com", "primary": true }],
      "given_name": "Jane",
      "family_name": "Doe",
      "display_name": "Jane Doe",
      "locale": "en-US",
      "zoneinfo": "Europe/Berlin",
      "state": "active",
      "attributes": { "department": "Engineering" },
      "groups": [{ "id": "dsg_01j9xn3p5q7r9s1t3v5w7x9y1a", "name": "Engineering" }],
      "user_id": "usr_01j9xq5r7s9t1v3w5x7y9z1a3c",
      "link_status": "linked",
      "drift": false,
      "created_at": "2026-10-20T09:00:00Z",
      "updated_at": "2026-10-20T09:05:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

link_status ist einer der Werte linked, invited, blocked_other_org, duplicate, mirror_only oder unlinked; user_id ist null, wenn der Datensatz nicht verknüpft ist. Leere Werte sind null.

Fehler

HTTP Code Wann
400 invalid_cursor Der Cursor ist ungültig oder gehört zu einem anderen Verzeichnis oder Filter.
404 not_found Das Verzeichnis existiert in dieser Umgebung nicht.
422 validation_failed state oder group_id ist ungültig oder wiederholt, limit liegt außerhalb des gültigen Bereichs, oder before bzw. order wurde angegeben (unsupported).
401 unauthenticated Die Anmeldedaten fehlen, sind ungültig oder wurden widerrufen.
403 insufficient_permissions Den Anmeldedaten fehlt die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.
503 service_unavailable Die Verzeichnissynchronisierung ist vorübergehend nicht verfügbar oder in dieser Bereitstellung nicht konfiguriert; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.

Beispiel

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

Personenbezogene Daten

Dieser Endpunkt enthält personenbezogene Daten: Verzeichnis-(SCIM-)Benutzer. Personenbezogene Daten in den KeenAuth-APIs beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).