Overview

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

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 [e-mail].

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.

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:

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