Organizations API
Organizations are an identity concept — they live in Hanzo IAM at api.hanzo.ai/v1/iam.
An organization is the top-level tenant: every cluster, project, machine, secret, and team member belongs to one. It is an identity object, so it lives in Hanzo IAM — not in a second directory owned by the deploy plane.
All calls take an IAM bearer — see Authentication.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/iam/get-organizations?owner=admin | List organizations visible to the caller |
GET | /v1/iam/get-organization?id=<owner>/<name> | One organization |
POST | /v1/iam/add-organization | Create an organization |
POST | /v1/iam/update-organization?id=<owner>/<name> | Update an organization |
POST | /v1/iam/delete-organization | Delete an organization |
These are administrative endpoints: a normal member bearer gets 403 forbidden. Org membership and roles for ordinary users are managed in the Console.
curl -fsS "https://api.hanzo.ai/v1/iam/get-organizations?owner=admin" \
-H "Authorization: Bearer $TOKEN"How the org reaches the rest of the API
You never pass an org id by hand. The gateway strips every client-supplied identity header and re-mints X-Org-Id from the validated JWT's owner claim, so each request is scoped to exactly the org the token belongs to. A call with no org context answers:
{ "status": 403, "error": "X-Org-Id required" }That is the signal to re-authenticate, not to add a header.
Related
- Hanzo IAM — identity, SSO, and org membership
- Authentication — the one OIDC integration path
How is this guide?
Last updated on