Crear un directorio

POST /v1/directories · permiso directories:write

Crea un directorio SCIM inactivo para una organización y su primer token SCIM. Entregue al proveedor de identidad (Okta, Entra ID, Google Workspace…) el base_url y el token. token solo se devuelve en esta respuesta, una vez; ningún endpoint lo devuelve después. La respuesta incluye Cache-Control: no-store, y una respuesta reproducida para el mismo Idempotency-Key omite token e incluye secret_redacted: true; si lo perdió, cree un nuevo token con POST /v1/directories/{directory_id}/tokens. La creación se audita como directory.created y directory.token_created (el token nunca entra en el registro de auditoría).

scim_host debe ser el host principal del entorno: su dominio personalizado activo; si no lo hay, <slug>.<region>.keenauth.app. La URL base SCIM del directorio es https://<scim_host>/scim/v2/<directory>.

Solicitud

Campo Tipo Obligatorio Descripción
organization_id cadena sí ID de la organización (org_…); debe existir en este entorno y estar activa.
name cadena sí De 1 a 64 caracteres, sin caracteres de control, sin espacios al inicio ni al final.
scim_host cadena sí El host principal del entorno (nombre DNS en minúsculas); debe enrutar a este entorno.
type cadena no scim (predeterminado; el único tipo en esta versión).
token_label cadena no Etiqueta del primer token, de 1 a 100 caracteres; predeterminada Initial token.

Respuesta

201 Created con el directorio, token_id y el token de un solo uso.

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

Errores

HTTP code Cuándo
404 not_found La organización no existe en este entorno.
409 organization_disabled La organización no está activa; no se crea ningún directorio.
409 organization_pending_deletion La organización está programada para eliminación; no se crea ningún directorio.
422 idempotency_key_reuse Idempotency-Key se usó para una solicitud distinta.
422 validation_failed Falta un campo o no es válido; /scim_host invalid cuando el host está mal formado o no enruta a este entorno.
401 unauthenticated La credencial falta, no es válida o fue revocada.
403 insufficient_permissions La credencial no tiene el permiso requerido.
429 rate_limited Se superó el límite de frecuencia; reintente después del tiempo indicado en Retry-After.
503 service_unavailable La sincronización de directorios no está disponible temporalmente o no está configurada en este despliegue; reintente después del tiempo indicado en Retry-After.

Ejemplo

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