Organization API

Manage your organization's profile, plan information, and membership roster.

Authentication: session token only (Authorization: Bearer <session_token>).

Looking for governance defaults?

Org-wide governance settings — default verdict mode, model allow/block lists, default spend caps, emergency kill switch — live on the Governance Controls API, not here.

---

Endpoints

Method	Path	Permission
GET	/v1/organization	organization:read
PATCH	/v1/organization	organization:update
GET	/v1/organization/users	users:read

---

GET /v1/organization

{
  "organization_id": "org_01JF8RORG1A2B3C4D5E6F7G8H9I",
  "organization_name": "Acme Corp",
  "plan": "pro",
  "status": "active",
  "domain": "acmecorp.com",
  "created_at": "2024-11-01T00:00:00Z"
}

Field	Type	Description
organization_id	string	Unique identifier (org_*)
organization_name	string	Display name
plan	string	starter, pro, or enterprise
status	string	active or suspended
domain	string | null	Verified primary domain, if configured
created_at	RFC 3339	When the organization was created

---

PATCH /v1/organization

Partial update.

{
  "organization_name": "Acme Corporation",
  "domain": "acmecorp.com"
}

Field	Type	Description
organization_name	string	Updated display name
domain	string	Primary domain — must be DNS-verifiable

Returns the updated organization object.

---

GET /v1/organization/users

A lightweight membership roster for the org. Useful for building admin dashboards or external user-sync workflows. The full per-user CRUD surface (and offset pagination) is on the Users API.

{
  "users": [
    {
      "user_id": "usr_01JF8RUS1A2B3C4D5E6F7G8H9I",
      "email": "jane.doe@yourcompany.com",
      "display_name": "Jane Doe",
      "roles": ["admin"],
      "status": "active",
      "last_login_at": "2026-04-30T09:30:00Z"
    }
  ],
  "total": 12
}

Pagination shape

/v1/organization/users returns a flat total count, no cursor. For paged access use GET /v1/users (offset pagination).

---

Errors

HTTP	error.code	Cause
400	validation_error	Body or query failed schema validation
401	unauthenticated	Missing or invalid session token
403	forbidden	Insufficient permissions

---

Next steps

• Manage users → Users API
• Define roles and permissions → Roles API
• Configure org-wide governance defaults → Governance Controls
• Authentication contract → Authentication