Create an organization

POST /v1/organizations · permission organizations:write

Creates an organization in the environment. The response carries an ETag. An organization.created event is published and the change is written to the management audit log.

Request

Field Type Required Description
Idempotency-Key header no Optional. 16-64 characters [A-Za-z0-9_-]; repeating the same key with the same request returns the same response.
name string yes Display name, 1-256 characters, no control characters.
slug string no 3-64 characters a-z, 0-9 and single hyphens; unique in the environment. Derived from the name when omitted.
external_id string | null no Your own identifier, up to 255 characters; unique in the environment. null clears it.
metadata object | null no JSON object, at most 16 KiB, 5 levels and 100 top-level keys. Returned only by the management API.
brand_color string | null no Brand color #RRGGBB; stored in upper case. null clears it.
max_memberships integer | null no Membership cap, at least 1; null means unlimited.
default_zoneinfo string | null no Default IANA time zone (for example Europe/Istanbul), used for sign-up, invitation, JIT SSO and SCIM in the organization context when the browser or IdP supplies none. null clears it (the environment default applies).

Request body:

{
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "metadata": {
    "tier": "gold"
  },
  "brand_color": "#1F6FEB"
}

Response

201 Created with the new organization.

{
  "id": "org_01j9xk3m7q8r2s4t6v8w0y2z4a",
  "name": "Acme Corp",
  "slug": "acme",
  "external_id": "crm-4821",
  "status": "active",
  "metadata": {
    "tier": "gold"
  },
  "brand_color": "#1F6FEB",
  "max_memberships": null,
  "default_zoneinfo": null,
  "created_via": "admin_api",
  "disabled_at": null,
  "deletion_requested_at": null,
  "deletion_due_at": null,
  "created_at": "2026-10-12T09:30:00.123456Z",
  "updated_at": "2026-10-12T09:30:00.123456Z",
  "version": 1
}

Errors

HTTP code When
400 unknown_field The body has a field that is not in the schema or is read-only (id, status…).
401 unauthenticated The credential is missing, invalid or revoked.
403 insufficient_permissions The credential lacks the required permission.
403 quota_exceeded The organization limit of the environment's plan (organizations_per_environment_max) is reached.
409 slug_taken The slug is used by another organization.
409 slug_reserved The slug is a reserved word or another organization's former slug (reserved for 90 days).
409 external_id_taken The external_id is used by another organization.
422 validation_failed A field is invalid (name, slug, external_id, metadata, brand_color, max_memberships, default_zoneinfo).
422 idempotency_key_reuse The Idempotency-Key was already used with a different request.
429 rate_limited The rate limit was exceeded; retry after the Retry-After period.
503 service_unavailable A dependency is temporarily unavailable; retry after the Retry-After period.

Example

curl -X POST "https://api.eu.keenauth.com/v1/organizations" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp","slug":"acme"}'