Ein Verzeichnis anlegen

POST /v1/directories · Berechtigung directories:write

Legt ein inaktives SCIM-Verzeichnis für eine Organisation und ihr erstes SCIM-Token an. Geben Sie dem Identity Provider (Okta, Entra ID, Google Workspace…) die base_url und das token. token wird nur in dieser Antwort und einmalig zurückgegeben; kein Endpunkt liefert es später erneut. Die Antwort trägt Cache-Control: no-store, und eine für denselben Idempotency-Key wiederholte Antwort lässt token weg und enthält secret_redacted: true; erstellen Sie mit POST /v1/directories/{directory_id}/tokens ein neues Token, falls Sie es verloren haben. Die Anlage wird als directory.created und directory.token_created protokolliert (das Token gelangt nie in das Audit-Protokoll).

scim_host muss der primäre Host der Umgebung sein: ihre aktive benutzerdefinierte Domain, andernfalls <slug>.<region>.keenauth.app. Die SCIM-Basis-URL des Verzeichnisses lautet https://<scim_host>/scim/v2/<directory>.

Anfrage

Feld Typ Pflicht Beschreibung
organization_id Zeichenkette ja Organisations-ID (org_…); sie muss in dieser Umgebung existieren und aktiv sein.
name Zeichenkette ja 1–64 Zeichen, keine Steuerzeichen, keine führenden oder nachgestellten Leerzeichen.
scim_host Zeichenkette ja Der primäre Host der Umgebung (DNS-Name in Kleinbuchstaben); er muss zu dieser Umgebung routen.
type Zeichenkette nein scim (Standard; in dieser Version der einzige Typ).
token_label Zeichenkette nein Bezeichnung des ersten Tokens, 1–100 Zeichen; Standard Initial token.

Antwort

201 Created mit dem Verzeichnis, token_id und dem einmaligen token.

{
  "id": "dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
  "organization_id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "type": "scim",
  "name": "Okta",
  "state": "inactive",
  "base_url": "https://acme.eu.keenauth.app/scim/v2/dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
  "created_at": "2026-10-19T09:31:00.123456Z",
  "last_request_at": null,
  "provisioning_mode": "user_store",
  "attribute_allowlist": [],
  "unverified_domain_action": "invite",
  "delete_action": "remove_membership",
  "on_delete_memberships": "keep",
  "mass_deprovision_guard": {"enabled": true, "percent": 10, "absolute_min": 25},
  "send_welcome_email": false,
  "token_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "token": "idp_scim_<token>"
}

Fehler

HTTP code Wann
404 not_found Die Organisation existiert in dieser Umgebung nicht.
409 organization_disabled Die Organisation ist nicht aktiv; es wird kein Verzeichnis angelegt.
409 organization_pending_deletion Die Organisation ist zur Löschung vorgemerkt; es wird kein Verzeichnis angelegt.
422 idempotency_key_reuse Der Idempotency-Key wurde für eine andere Anfrage verwendet.
422 validation_failed Ein Feld fehlt oder ist ungültig; /scim_host invalid, wenn der Host fehlerhaft ist oder nicht zu dieser Umgebung routet.
401 unauthenticated Die Anmeldeinformation fehlt, ist ungültig oder widerrufen.
403 insufficient_permissions Die Anmeldeinformation besitzt nicht die erforderliche Berechtigung.
429 rate_limited Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Zeit aus Retry-After.
503 service_unavailable Die Verzeichnissynchronisation 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 -X POST "https://api.eu.keenauth.com/v1/directories" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"organization_id":"org_01j9xk3m7q8r2s4t6v8w0y2z4a","name":"Okta","scim_host":"acme.eu.keenauth.app"}'