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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Overview

> Create and manage access groups, their members, and role bindings via the REST API. Enterprise feature.

<Note>
  **Available on Enterprise plans.** An organization without an Enterprise plan is refused with HTTP 402 and the error code `enterprise_plan_required`. Self-hosted deployments need an Enterprise license for the same endpoints. To enable it, reach out to [enterprise@langwatch.ai](mailto:enterprise@langwatch.ai).
</Note>

## Intro

The Groups API lets you manage LangWatch access groups via REST. Groups are collections of users that share the same role bindings — when you assign a role to a group, every member inherits that access.

Groups can be created manually via the API or provisioned automatically from your identity provider via [SCIM](/docs/platform/scim).

## Authentication

The Groups API requires an **organization-level API key** with `organization:manage` permission (created in Settings > API Keys). Pass it as a Bearer token:

```
Authorization: Bearer sk-lw-<id>_<secret>
```

## Endpoints

### Groups

| Method   | Path               | Description                                             |
| -------- | ------------------ | ------------------------------------------------------- |
| `GET`    | `/api/groups`      | List all groups in the organization                     |
| `POST`   | `/api/groups`      | Create a new group (with optional members and bindings) |
| `GET`    | `/api/groups/{id}` | Get group details with members and bindings             |
| `PATCH`  | `/api/groups/{id}` | Rename a group                                          |
| `DELETE` | `/api/groups/{id}` | Delete a group and all its memberships/bindings         |

### Members

| Method   | Path                                | Description                  |
| -------- | ----------------------------------- | ---------------------------- |
| `GET`    | `/api/groups/{id}/members`          | List members of a group      |
| `POST`   | `/api/groups/{id}/members`          | Add a member to a group      |
| `DELETE` | `/api/groups/{id}/members/{userId}` | Remove a member from a group |

### Role Bindings

| Method   | Path                                    | Description                        |
| -------- | --------------------------------------- | ---------------------------------- |
| `GET`    | `/api/groups/{id}/bindings`             | List role bindings for a group     |
| `POST`   | `/api/groups/{id}/bindings`             | Add a role binding to a group      |
| `DELETE` | `/api/groups/{id}/bindings/{bindingId}` | Remove a role binding from a group |

## SCIM-Managed Groups

Groups provisioned from an identity provider via SCIM are marked with a `scimSource` field (e.g. `"azure-ad"`, `"okta"`). SCIM-managed groups have restrictions:

* **Cannot be renamed** via this API (the IdP is the source of truth)
* **Cannot have members added or removed** manually (membership is managed by the IdP)
* Role bindings can still be managed via this API

## Typical Flow

1. Create an admin API key in Settings > API Keys with `organization:manage` permission
2. Create a group with initial members and role bindings:

```bash theme={null}
curl -X POST https://app.langwatch.ai/api/groups \
  -H "Authorization: Bearer sk-lw-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Engineers",
    "memberIds": ["user_abc", "user_def"],
    "bindings": [
      {
        "role": "MEMBER",
        "scopeType": "TEAM",
        "scopeId": "<team_id>"
      }
    ]
  }'
```

3. All members inherit the MEMBER role on the specified team and all its projects.

## Role Binding Scopes

Bindings can target three scope levels:

| Scope Type     | Description                                    |
| -------------- | ---------------------------------------------- |
| `ORGANIZATION` | Access to all teams and projects in the org    |
| `TEAM`         | Access to a specific team and all its projects |
| `PROJECT`      | Access to a specific project only              |

Available roles: `ADMIN`, `MEMBER`, `VIEWER`, `CUSTOM` (requires `customRoleId`).

## Errors

| Code                                  | Status | Meaning                                                                                    |
| ------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `group_not_found`                     | 404    | No such group in this organization                                                         |
| `scim_managed_group`                  | 409    | The group is provisioned over SCIM, so it is renamed, changed and deleted in the directory |
| `user_not_in_organization`            | 422    | The user is not a member here                                                              |
| `group_member_already_added`          | 409    | They are already in the group                                                              |
| `scope_not_in_organization`           | 422    | The team or project belongs to another organization                                        |
| `custom_role_id_required`             | 422    | Role is `CUSTOM` with no `customRoleId`                                                    |
| `custom_role_not_assignable`          | 422    | That custom role cannot be granted here                                                    |
| `role_binding_not_found`              | 404    | No such binding on this group                                                              |
| `personal_workspace_not_managed_here` | 403    | The scope is somebody's personal workspace                                                 |