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.
Groups are an Enterprise feature. Contact your account team to enable them.
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
- Create an admin API key in Settings > API Keys with
organization:manage permission
- Create a group with initial members and role bindings:
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>"
}
]
}'
- 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 |
ADMIN, MEMBER, VIEWER, CUSTOM (requires customRoleId).
