# Organizations API

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

**URL:** https://inference.sh/docs/api/rest/orgs
**Last updated:** 2026-10-11

---

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](/docs/org/organizations).

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](https://app.inference.sh/settings/team/keys).

→ [Workspaces API](/docs/api/rest/teams) · [Workspace settings view](/docs/api/rest/teams#workspace-settings-view) · [Entitlements — Organizations](/docs/api/rest/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

| Field | Required | Description |
|-------|----------|-------------|
| `name` | yes | Display name |
| `slug` | yes | Unique slug (2–40 lowercase letters, numbers, hyphens). Also becomes the org workspace username |

```json
{
  "name": "Acme Inc",
  "slug": "acme"
}
```

### 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`)

| Field | Description |
|-------|-------------|
| `id` | Organization ID (same as the org workspace team ID) |
| `slug` | URL slug |
| `name` | Display name |
| `avatar_url` | Icon URL when set |
| `default_team_id` | Workspace new managed users land in when not specified |
| `is_admin` | Whether **you** are on the org admin grant list |

Org usage policy is **not** a field on `OrgDTO`. Read or change it with the [organization usage policy](#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`)

| Field | Description |
|-------|-------------|
| `name` | New display name |
| `avatar_url` | Icon URL, or empty string to remove |
| `default_team_id` | Default member workspace for provisioning |

---

## 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`:

| Field | Description |
|-------|-------------|
| (team fields) | Same as `TeamDTO`: `id`, `type`, `name`, `username`, `org_id`, `status`, … |
| `kind` | `org` for the organization workspace, `org_member` for member teams |
| `member_count` | Current member count |
| `can` | Capability strings **you** hold on that workspace (same identifiers as [`GET /teams/{id}/view`](/docs/api/rest/teams#workspace-settings-view)). On member teams, org **owners** receive owner capabilities (for example `manage_admins`, `archive`); org **admins** receive admin capabilities (`manage_members`, not `manage_admins`). Billing for member teams still appears on the org workspace's `can`, not here, when the org pays. Use per-row `can` (for example `manage_admins`) for provisioning and role pickers — do not infer admin rights from your role on the organization workspace alone. |

---

## 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:

```json
{
  "team_id": "team_standalone"
}
```

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`](/docs/api/rest/teams#create-workspace) (`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`

```json
{
  "email": "admin@acme.com"
}
```

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.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/orgs/{id}/users` | List managed users |
| `POST` | `/orgs/{id}/users` | Provision by email (`OrgProvisionUserRequest`: `email`, optional `name`, `team_id`, `role`) |
| `POST` | `/orgs/{id}/users/{userId}/deactivate` | Deactivate managed account |
| `POST` | `/orgs/{id}/users/{userId}/reactivate` | Reactivate managed account |

All require **`manage_org`** (read for `GET`, write for mutations). See [Organizations — Managed accounts](/docs/org/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).

| `role` | Who may provision |
|--------|-------------------|
| `member` | Any caller with **`manage_org`** (org admins have admin standing on member workspaces) |
| `admin` | Caller must have **`manage_admins`** on the **target** workspace — the same grant rule as [invites and member role changes](/docs/api/rest/teams#members). An org **owner** satisfies this on every member workspace without roster membership. An org **admin** on the org workspace only cannot provision workspace admins until they are **owner** on that team or an org owner provisions for them. |

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](#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](/docs/api/rest/teams).

---

## 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.

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/orgs/{id}/rules` | The org's governance layer (`PolicyLayerDTO`) |
| `PUT` | `/orgs/{id}/rules` | Replace reach and usage rules in full (`PolicyLayerSetRequest`) |
| `DELETE` | `/orgs/{id}/rules` | Clear the org's layer |
| `POST` | `/orgs/{id}/rules` | Add one agent-action rule |
| `PUT` | `/orgs/{id}/rules/{ruleId}` | Change one rule's `enforcement` |
| `DELETE` | `/orgs/{id}/rules/{ruleId}` | Remove one rule |
| `POST` | `/orgs/{id}/rules/explain` | Test a call against the layers in force |
| `GET` | `/orgs/{id}/rules/denials` | Blocked-attempt feed (`PolicyDenialDTO[]`) |

Field-level reference, workspace and member-policy routes, and effective access are in the [Usage policy API](/docs/api/rest/usage-policy). Product behavior is in [Usage policy](/docs/org/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](/docs/api/rest/overview): authentication and errors
- [Billing](/docs/api/rest/billing): org payer workspace and `manage_billing`
- [Usage policy](/docs/org/usage-policy): reach, categories, and enforcement (API above and on `/teams/{id}/rules`)