Organizations API

Manage organizations: the company layer above workspaces, shared billing, org admins, and attaching or creating member workspaces.

An organization's ID is the same as its organization workspace (type: "org"). Most org admin routes require the manage_org capability on that workspace (org admins). User-facing concepts are in Organizations overview.

Requires API key scopes teams:read (read org and list teams) or teams:write (create org, attach teams, admin changes). Create keys in settings → workspace → api keys.

→ Workspaces API · Workspace settings view · Entitlements — Organizations

Create organization

POST /orgs

Creates an organization and its organization workspace. The caller becomes the first org admin (owner on the org workspace). Requires teams:write and the create_org capability on your current workspace context (standalone workspace owner; not available from org member workspaces or managed accounts).

Request

1{2  "name": "Acme Inc",3  "slug": "acme"4}

Response

OrgDTO with is_admin: true for the caller.

Get organization

GET /orgs/{idOrSlug}

Returns one organization by ID or slug. Requires teams:read. Visible to org admins and members of any workspace in the org; others receive 404.

Response (OrgDTO)

Org usage policy is not a field on OrgDTO. Read or change it with the organization usage policy routes.

Update organization

POST /orgs/{id}

Updates display fields on the organization workspace and org metadata. Requires teams:write and manage_org on the org workspace. Absent JSON fields are left unchanged; send "avatar_url": "" to clear the icon.

Request (OrgUpdateRequest)

List organization workspaces

GET /orgs/{id}/teams

Lists every workspace in the organization, including the org workspace itself, with live member counts. Requires teams:read and manage_org.

Response

Array of OrgTeamDTO:

Attach workspace

POST /orgs/{id}/teams

Attaches an existing standalone workspace to the organization. Requires teams:write, manage_org, and ownership of the workspace being attached. Body:

1{2  "team_id": "team_standalone"3}

Both an org admin and the standalone workspace's owner must agree (the API enforces both).

Create workspace in org

POST /orgs/{id}/teams/create

Creates a new workspace born inside the organization (billed and governed by the org from creation). Requires teams:write and manage_org. Accepts the same body as POST /teams (name, username, email).

Managed org admins use this path when they cannot create a standalone workspace.

Org admins

List admins

GET /orgs/{id}/admins

Returns the org admin grant list (OrgAdminDTO: id, org_id, user_id, nested user). Requires teams:read and manage_org.

Add admin

POST /orgs/{id}/admins

1{2  "email": "[email protected]"3}

Requires teams:write and manage_admins on the org workspace (org owners only). The user must already be a member of the organization workspace. Additions go through the same membership rules as workspace members.

Remove admin

DELETE /orgs/{id}/admins/{userId}

Requires teams:write and manage_admins. Cannot remove the last owner from the org workspace (400, code last_owner).

Managed users (enterprise)

Org admins provision accounts that live only inside the organization.

All require manage_org (read for GET, write for mutations). See Organizations — Managed accounts.

Provision (POST /orgs/{id}/users) accepts role member (default) or admin on the target workspace (team_id, or the org's default_team_id). owner is not allowed. The org workspace itself accepts only admin (not plain members).

A failed grant returns 403 with code team_role_required (often with meta.capability set to manage_admins). The check runs before a new managed account is created.

When building provision flows, read each workspace's can from List organization workspaces. If the user switches team_id, re-evaluate whether admin is offered (manage_admins on the newly selected workspace).

Deactivate sets an org-level suspension on the managed user, revokes all sessions, and refuses sign-in and authenticated requests until Reactivate clears it. Reactivate only removes the org suspension; it never clears a platform ban (banned_at from staff).

On successful sign-in, a deactivated managed account receives 403 with code account_deactivated and a message to ask an org admin. A platform-banned account (including a managed user) receives 403 with code account_banned.

GET /orgs/{id}/users returns each managed user as a UserDTO. For the org admin UI, banned_at is populated when the account cannot sign in—either because the org deactivated it or because staff banned it—so integrators can treat non-null banned_at as “cannot sign in.” Staff ban notes are not returned on managed-user rows (ban_note is omitted).

Org SSO

SAML SSO anchored at the organization uses routes under /orgs/{id}/sso (GET, PUT, DELETE, POST …/test). Same manage_org gate as other org settings. Team-level SAML for a single workspace remains under /teams/{id}/saml on the Workspaces API.

Verified domains

GET /orgs/{id}/domains lists verified email domains for the org (manage_org). Changing the list is not part of the public API.

Organization usage policy

The org-wide usage policy is the organization's governance layer in the rules API. Routes take the org ID (the organization workspace team ID). Reads need teams:read and view_policy; writes and the blocked-attempts feed need manage_policy on the org workspace.

Field-level reference, workspace and member-policy routes, and effective access are in the Usage policy API. Product behavior is in Usage policy.

Delete organization

There is no DELETE /orgs/{id}. Archive the organization workspace with DELETE /teams/{id} on the org workspace ID when policy allows (archive capability). That archives the org and its workspaces together.

Related

• REST overview: authentication and errors
• Billing: org payer workspace and manage_billing
• Usage policy: reach, categories, and enforcement (API above and on /teams/{id}/rules)