Organizations

An organization is the top-level tenant: the membership, billing and administration boundary. It owns the infrastructure shared by everything inside it (models and provider credentials, proxies, the package catalog, custom roles) and contains one or more spaces, where the work happens.

Organization ids are bare UUIDs, with no prefix. Each organization also has a unique slug, which becomes the default scope of the packages it authors (@<slug>/<name>).

Creating an organization

After signing up, the onboarding flow guides you through creating your first organization. Creating one needs your own user credential (not an API key or an OAuth client):

curl -X POST https://your-instance/api/orgs \
  -H "Cookie: ..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Corp" }'

name is required. slug is optional (kebab-case) and derived from the name when omitted. A slug that is taken answers 400 slug_taken. You become the owner.

A new organization gets a default space and a starter agent activated in it. It is also pinned to the current API version.

An operator can close organization creation on an instance, so that only platform admins can create organizations and everyone else waits for an invitation (403 org_creation_disabled). See Environment Variables. GET /api/profile answers can_create_org, which says whether POST /api/orgs would accept you.

Roles

An organization can have several owners and always keeps at least one. What each role can do in detail, and how space roles combine with it, is in Roles and permissions.

Who may change whose role:

• Nobody changes their own role.
• An owner manages every other member, owners included, and is the only one who can assign owner.
• An admin manages members and guests and can assign guest, member or admin.
• Granting owner, changing or removing an owner, and leaving the organization require the dashboard session. API keys, OAuth clients, MCP clients and CLI tokens are refused, even when their user is an owner.

There is no ownership-transfer endpoint. To transfer, promote the new owner, then demote yourself or leave.

Inviting members

All invitations are explicit: the person receives a link, signs in or signs up, and accepts.

curl -X POST https://your-instance/api/orgs/<org id>/members \
  -H "Cookie: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "member",
    "space_assignments": [{ "spaceId": "spc_...", "preset_role": "operator" }]
  }'

• role is guest, member or admin (default member). owner is reached by changing the role of an existing member.
• space_assignments (optional) lists the spaces the person joins, with a preset or custom role each. They are applied when the invitation is accepted.
• When SMTP is configured, an email is sent. Otherwise the response carries a token to share yourself, and the invite page is /invite/<token>.
• A second invitation for the same email answers 409 with the invitation_id to edit instead.
• PATCH /api/orgs/{orgId}/invitations/{invitationId} changes the role or the assignments of a pending invitation, DELETE cancels it.

Managing members

# Change a role (owner or admin, within the rules above)
curl -X PUT https://your-instance/api/orgs/<org id>/members/<user id> \
  -H "Cookie: ..." -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

# Remove a member
curl -X DELETE https://your-instance/api/orgs/<org id>/members/<user id> -H "Cookie: ..."

# Leave (dashboard session only)
curl -X POST https://your-instance/api/orgs/<org id>/leave -H "Cookie: ..."

GET /api/orgs/{orgId} returns the organization, its members (with members:read) and its pending invitations (with members:invite). There is no separate member list endpoint.

A member who leaves or is removed loses their explicit space roles and notifications in the organization, their schedules there are disabled, their API keys there are revoked, and their personal space enters a 30-day offboarding window. The last owner cannot leave (409 last_owner): promote someone else first or delete the organization. A JWT access token is not revocable and stays valid until it expires, but every request is checked against live membership.

In the web app, Organization settings > Users manages members and invitations, and Organization settings > Roles manages custom roles.

Organization settings

GET /api/orgs/{orgId}/settings is readable by any member. PATCH /api/orgs/{orgId}/settings needs org:settings (owner or admin) and merges the keys you send:

Deleting an organization

DELETE /api/orgs/{orgId} is owner-only and deletes the organization with its spaces, packages, runs, files, webhooks and keys. It is refused with a 400 delete_failed while a run is in progress. While a deletion is reserved, new runs and chat turns are refused with 409 org_deleting.

Selecting an organization

A browser session names the active organization with the X-Org-Id header. An API key is bound to one organization: the header is ignored with an API key, and only X-Space-Id is checked. GET /api/orgs lists the organizations of the caller.

Each organization is also reachable as its own MCP server endpoint.

What belongs to the organization

• Models and provider credentials, proxies and the default of each. See LLM Models and Proxies.
• The package catalog: agents, skills, integrations and MCP servers are owned by the organization and placed in spaces. See Library and sharing.
• Custom roles and the OAuth clients registered at the organization level.
• Organization-wide integration OAuth clients, inherited by every space.