Organization

The organization is implied by the token — there is no org id in any path.

org:write changes exactly the settings the portal's Settings → Organization form edits. Suspending or deleting the organization and changing its billing mode are done in the portal.

The organization object

For an Admin token owner, the organization record and its settings are returned as one flat object. Settings fields appear once they have been set; an organization that never set monthly_budget, for example, has no monthly_budget key.

Treat the object as open: new fields may appear within v1.

The organization identity (members)

A token owner who is not an Admin gets only the organization's identity. Settings and billing mode are admin-only.

{
  "id": "3f9a7c21-5d4e-4b8a-9c0f-1e2d3a4b5c6d",
  "name": "Acme Corp",
  "slug": "acme",
  "region": "default",
  "is_active": true,
  "created_at": "2026-03-02T09:41:17Z",
  "role": "member"
}

Retrieve the organization

GET /api/v1/mgmt/org

An Admin gets the organization object; any other member gets the organization identity.

curl https://portal.<domain>/api/v1/mgmt/org \
  -H "Authorization: Bearer $TF_PAT"

import os
import requests

resp = requests.get(
    "https://portal.<domain>/api/v1/mgmt/org",
    headers={"Authorization": f"Bearer {os.environ['TF_PAT']}"},
    timeout=30,
)
resp.raise_for_status()
org = resp.json()
print(org["name"], org.get("budget_behavior"))

{
  "id": "3f9a7c21-5d4e-4b8a-9c0f-1e2d3a4b5c6d",
  "name": "Acme Corp",
  "slug": "acme",
  "is_active": true,
  "billing_mode": "prepaid",
  "region": "default",
  "created_at": "2026-03-02T09:41:17Z",
  "spend_ceiling": 10000,
  "default_model_allowlist": ["openai/gpt-4o-mini"],
  "default_rpm_limit": 600,
  "default_monthly_cap": 1000,
  "monthly_budget": 5000,
  "budget_behavior": "alert_only",
  "email_otp_enabled": true
}

Retrieve the organization settings

GET /api/v1/mgmt/org/settings

Admin only. Returns the organization object with every settings key. A member gets 403 insufficient_scope.

curl https://portal.<domain>/api/v1/mgmt/org/settings \
  -H "Authorization: Bearer $TF_PAT"

Update the organization

PATCH /api/v1/mgmt/org

Send any of the fields below at the top level of the body. Only the fields you send change; an empty body or an unknown field is 400 invalid_request (param names the field). Requires Idempotency-Key and an owner who is currently an Admin. Returns 200 with the updated organization object.

curl -X PATCH https://portal.<domain>/api/v1/mgmt/org \
  -H "Authorization: Bearer $TF_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f" \
  -d '{"monthly_budget": 6000, "budget_behavior": "hard_stop"}'

import uuid

resp = requests.patch(
    "https://portal.<domain>/api/v1/mgmt/org",
    headers={
        "Authorization": f"Bearer {os.environ['TF_PAT']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"monthly_budget": 6000, "budget_behavior": "hard_stop"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json()["budget_behavior"])

Errors specific to the organization