> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bentralabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Administration

The organization's details, its members and invitations, workspaces and who is in them, and groups.

| Method | Path | Scope | MCP tool |
| - | - | - | - |
| `GET` | `organization/` | `read:org` | `get_organization` |
| `PATCH` | `organization/` | `manage:org` | `update_organization` |
| `DELETE` | `organization/` | `manage:org` | `delete_organization` |
| `GET` | `members/` | `read:org` | `list_members` |
| `PATCH` | `members/{id}/` | `manage:members` | `change_member_role` |
| `DELETE` | `members/{id}/` | `manage:members` | `remove_member` |
| `GET` | `invitations/` | `manage:members` | `list_invitations` |
| `POST` | `invitations/` | `manage:members` | `invite_member` |
| `DELETE` | `invitations/{id}/` | `manage:members` | `revoke_invitation` |
| `GET` | `workspaces/` | `read:org` | `list_workspaces` |
| `GET` | `workspaces/{slug}/` | `read:org` | — |
| `POST` | `workspaces/` | `manage:workspaces` | `create_workspace` |
| `PATCH` | `workspaces/{slug}/` | `manage:workspaces` | `update_workspace` |
| `DELETE` | `workspaces/{slug}/` | `manage:workspaces` | `delete_workspace` |
| `GET` | `workspaces/{slug}/members/` | `read:org` | `list_workspace_members` |
| `POST` | `workspaces/{slug}/members/` | `manage:members` | `add_workspace_member` |
| `PATCH` | `workspaces/{slug}/members/{id}/` | `manage:members` | `change_workspace_member_role` |
| `DELETE` | `workspaces/{slug}/members/{id}/` | `manage:members` | `remove_workspace_member` |
| `GET` | `groups/` | `read:org` | `list_groups` |
| `GET` | `groups/{id}/` | `read:org` | `get_group` |
| `POST` | `groups/` | `manage:members` | `create_group` |
| `PATCH` | `groups/{id}/` | `manage:members` | `update_group` |
| `DELETE` | `groups/{id}/` | `manage:members` | `delete_group` |
| `POST` | `groups/{id}/members/` and `groups/{id}/members/remove/` | `manage:members` | `add_group_member`, `remove_group_member` |
| `POST` | `groups/{id}/owners/` and `groups/{id}/owners/remove/` | `manage:members` | `add_group_owner`, `remove_group_owner` |
| `POST` | `groups/{id}/workspaces/` and `groups/{id}/workspaces/remove/` | `manage:members` | `grant_group_workspace_access`, `revoke_group_workspace_access` |

Request-portal branding is on [Organization](https://docs.bentralabs.com/reference/api/organization.md#request-portal-branding).

***

## Organization

### `GET organization/`

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
{"id": "…", "name": "Acme", "slug": "k3j9x2m4pqrt", "description": "", "plan": "business",
 "your_role": "admin"}
```

`slug` is the organization's URL ID: 12 characters generated when the org is created, never derived from the name, and it never changes. Names don't have to be unique.

### `PATCH organization/`

`{"description": "Platform engineering"}`. **Permission:** `org.manage_settings`. The name and ID can't be changed through the API.

### `DELETE organization/`

`{"confirm": "Acme"}` (or `?confirm=Acme`): the organization's exact name. **Owners only.** Deletes the organization and everything in it (workspaces, workflows, runs, requests, secrets; its encryption key is destroyed). Can't be undone. `204` on success, `400` if the name doesn't match, `403` for non-owners. On a one-organization plan (Free, Team) the account goes with it, so the owner can create a new organization.

***

## Members

Organization roles:

| Role | Can |
| - | - |
| `owner` | Everything. An organization always keeps at least one owner. |
| `admin` | Everything except the owner role: only owners can make someone an owner, or change or remove an owner. |
| `member` | Create workflows and workspaces, and use the workspaces they belong to. |
| `requester` | Only the request portal: submit and follow their own requests, and approve where designated. Takes no seat. |

### `GET members/`

**Permission:** `org.view_members`. Paginated. `?q=` matches username or email; `?role=` filters.

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
{"count": 2, "next": null, "previous": null,
 "results": [{"id": "…", "user_id": 7, "username": "bob", "email": "bob@acme.com", "name": "Bob Lee",
              "role": "member", "created_at": "…"}]}
```

### `PATCH members/{id}/`

`{"role": "admin"}`. **Permission:** `org.manage_members`.

Making someone a `requester` removes them from every workspace and revokes their API tokens. `403` when a non-owner grants, changes or removes the owner role; `400` when demoting the last owner; `409` when promoting a requester would go over the license's user limit.

### `DELETE members/{id}/`

Removes the person from the organization: their workspace memberships, group memberships and roles are deleted and their API tokens for the organization are revoked. A group they were the only owner of is left without owners (organization admins can still manage it). **Permission:** `org.manage_members`; removing an owner needs an owner. `400` for the last owner. Returns `204`.

***

## Invitations

**Permission:** `org.manage_members`.

### `POST invitations/`

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
{"email": "dana@acme.com", "role": "requester"}
```

Bentra emails an invitation link, valid for 7 days. **Response** `201`:

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
{"success": true, "invitation": {"id": "…", "email": "dana@acme.com", "role": "requester",
 "status": "pending", "invited_by": "alice", "created_at": "…", "expires_at": "…"}}
```

**Errors:** `400` invalid email or role; `403` inviting an owner without being one; `409` already a member, an invitation is already pending, or the user limit is reached; `429` more than 30 invitations in an hour; `502` the email couldn't be sent.

### `GET invitations/`

Pending invitations that haven't expired. Paginated.

### `DELETE invitations/{id}/`

Revokes a pending invitation. `400` if it isn't pending. Returns `204`.

***

## Workspaces

Workspaces are addressed by slug. Organization admins (`org.manage_workspaces`) see every workspace; others see the ones they belong to.

### `POST workspaces/`

`{"name": "Data Platform", "description": "…"}`. **Permission:** `org.create_workspace`. The slug comes from the name; you join the new workspace as its owner.

**Response** `201`: `{"success": true, "workspace": {"id", "slug", "name", "description", "is_default"}}`. `409` if the slug is taken.

### `PATCH workspaces/{slug}/`

`{"name": "…", "description": "…"}`. **Permission:** `org.manage_workspaces`. Renaming changes the slug, and with it the workspace's URLs.

### `DELETE workspaces/{slug}/`

**Permission:** `org.manage_workspaces`. Only empty workspaces: one with workflows, forms, runs, requests, variable collections or runner pools returns `409` with `counts`. The default workspace can't be deleted (`400`). Deleting a workspace with its contents is only possible in the UI. Returns `204`.

### Workspace members

**Permission:** `workspace.manage_members` on that workspace. Workspace roles: `owner`, `admin`, `member`. Requesters can't join workspaces.

* `GET workspaces/{slug}/members/` → `{"success": true, "members": [{"id", "user_id", "username", "email", "role"}]}`
* `POST workspaces/{slug}/members/` with `{"user": "bob", "role": "member"}` → `201`, or `409` if already a member. With `{"group": "Platform", "role": "member"}` it adds each of the group's members and returns `{"added": 3, "skipped": 1}` (already members and requesters are skipped).
* `PATCH workspaces/{slug}/members/{id}/` with `{"role": "admin"}`.
* `DELETE workspaces/{slug}/members/{id}/` → `204`. They stay in the organization.

***

## Groups

Groups collect organization members. A group can be a workflow's [approver](https://docs.bentralabs.com/reference/api/workflow-access.md#approvers), hold a [workflow role](https://docs.bentralabs.com/reference/api/workflow-access.md#roles), and be given access to workspaces.

Who can manage a group: organization admins (`org.manage_groups`) and the group's own owners. Only organization admins can create groups and grant them workspace access.

### `GET groups/` and `GET groups/{id}/`

**Permission:** `org.view_members`. The detail includes owners, members and workspace access:

```json theme={"theme":{"light":"github-light","dark":"night-owl"}}
{"id": "…", "name": "Platform", "description": "", "member_count": 3, "created_at": "…",
 "owners": [{"id": "…", "user_id": 1, "username": "alice", "email": "alice@acme.com"}],
 "members": [{"id": "…", "user_id": 7, "username": "bob", "email": "bob@acme.com"}],
 "workspaces": [{"id": "…", "workspace": "data", "workspace_name": "Data", "role": "member"}]}
```

### `POST groups/`

`{"name": "Platform", "description": "…"}`. You become its first owner. `409` if the name is taken.

### `PATCH groups/{id}/` and `DELETE groups/{id}/`

Rename, change the description, or delete. Deleting a group removes the approver and role grants made to it.

### Members and owners

`POST groups/{id}/members/`, `groups/{id}/members/remove/`, `groups/{id}/owners/` or `groups/{id}/owners/remove/` with `{"user": "bob"}`. Each returns the updated group. A group keeps at least one owner (`400`).

### Workspace access

`POST groups/{id}/workspaces/` with `{"workspace": "data", "role": "member"}` grants access, or changes the role if already granted. `POST groups/{id}/workspaces/remove/` with `{"workspace": "data"}` takes it away. Organization admins only.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.