Create a directory

POST /v1/directories · permission directories:write

Creates an inactive SCIM directory for an organization and its first SCIM token. Give the identity provider (Okta, Entra ID, Google Workspace…) the base_url and the token. token is returned only in this response, once; no endpoint returns it later. The response carries Cache-Control: no-store, and a response replayed for the same Idempotency-Key omits token and carries secret_redacted: true; create a new token with POST /v1/directories/{directory_id}/tokens if you lost it. The creation is audited as directory.created and directory.token_created (the token never enters the audit log).

scim_host must be the environment's primary host: its active custom domain, otherwise <slug>.<region>.keenauth.app. The directory's SCIM base URL is https://<scim_host>/scim/v2/<directory>.

Request

Field Type Required Description
organization_id string yes Organization ID (org_…); it must exist in this environment and be active.
name string yes 1–64 characters, no control characters, no leading or trailing spaces.
scim_host string yes The environment's primary host (lower-case DNS name); it must route to this environment.
type string no scim (default; the only type in this release).
token_label string no Label of the first token, 1–100 characters; default Initial token.

Response

201 Created with the directory, token_id and the one-time 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>"
}

Errors

HTTP code When
404 not_found The organization does not exist in this environment.
409 organization_disabled The organization is not active; no directory is created.
409 organization_pending_deletion The organization is scheduled for deletion; no directory is created.
422 idempotency_key_reuse The Idempotency-Key was used for a different request.
422 validation_failed A field is missing or invalid; /scim_host invalid when the host is malformed or does not route to this environment.
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable Directory sync is temporarily unavailable or not configured in this deployment; retry after the Retry-After period.

Example

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