Organizations (platform admin)

List, provision, and manage tenants (organizations) across the deployment. provision_org is the reciprocal of self-service registration — for operators standing up a tenant on a customer's behalf.

::: tip Auth

• GET /v1/admin/orgs — any platform admin.
• POST /v1/admin/orgs — platform Admin or higher.
• PATCH /v1/admin/orgs/:id — platform Admin or higher. :::

---

GET /v1/admin/orgs

List tenants, newest-first, with offset pagination.

Request

GET /v1/admin/orgs?q=<term>&page=<n>&page_size=<n>

Query param	Type	Notes
q	string	Free-text term matched against org name and slug. Blank/absent lists all.
page	int	1-indexed. Defaults to 1.
page_size	int	Defaults to 25, clamped to [1, 100].

Response

200 OK

{
  "items": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Acme Inc",
      "slug": "acme",
      "created_at": "2026-01-15T10:00:00Z",
      "suspended": false
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 25
}

Field	Type	Meaning
items[].id	UUID	Tenant id.
items[].name	string	Display name.
items[].slug	string	URL-safe slug.
items[].created_at	string	RFC3339 creation time.
items[].suspended	bool	true when the tenant is soft-deleted / suspended.
total / page / page_size	int	Offset-pagination envelope.

---

POST /v1/admin/orgs

Provision a new tenant and its first owner user in one call.

Request

POST /v1/admin/orgs

{
  "organization_name": "Acme Inc",
  "organization_slug": "acme",
  "owner_email": "owner@acme.com",
  "owner_password": "a-strong-password-min-12",
  "owner_display_name": "Acme Owner"
}

Field	Type	Required	Notes
organization_name	string	yes	Display name of the new tenant.
organization_slug	string	no	URL-safe slug. Derived from the name when omitted.
owner_email	string	yes	Email of the tenant's first owner.
owner_password	string	yes	Initial password (min 12 chars). The owner can reset it later.
owner_display_name	string	no	Optional display name for the owner.

Response

201 Created

{
  "organization_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "owner_user_id": "a3f1c2d4-…",
  "slug": "acme"
}

---

PATCH /v1/admin/orgs/:id

Rename and/or suspend/restore a tenant.

Request

PATCH /v1/admin/orgs/:id

{ "name": "Acme Corporation", "suspended": true }

Field	Type	Notes
name	string	Optional. Rename the tenant.
suspended	bool	Optional. true soft-deletes (suspends); false restores.

Response

200 OK

Returns the updated org row (same shape as one GET list element).

---

Error responses

Status	Code	When
401	authentication_required	No valid auth credential.
403	forbidden	Caller lacks the required platform role.
403	csrf_failed	Cookie-authed POST/PATCH without a valid X-IdentSphere-CSRF header.
400	invalid_input	Missing/invalid fields, bad slug, or weak owner password.
409	conflict	Slug or owner email already in use.
404	not_found	No such org (PATCH).