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

# Access Control (RBAC)

> Roles, permissions, custom roles and role bindings: who can do what in an organization, a team or a project.

> [!NOTE]
>
> **Custom roles, role bindings and groups are Enterprise features.** The built-in organization and
> team roles work on every plan. Creating custom roles, listing role bindings and creating groups
> need an Enterprise plan, and a self-hosted deployment needs an Enterprise license. The [Roles
> API](https://langwatch.ai/docs/api-reference/roles/overview.md) refuses calls without one with HTTP 402 and the error code
> `enterprise_plan_required`. To enable it, contact
> [enterprise@langwatch.ai](mailto:enterprise@langwatch.ai).

Teams and the built-in Admin, Member and Viewer roles work on every plan.
Creating or editing a custom role requires Enterprise.

![Built-in roles and the New role action in LangWatch](https://mintcdn.com/langwatch/trhmk6UoMcYE0dx4/images/access/roles-light.png?fit=max\&auto=format\&n=trhmk6UoMcYE0dx4\&q=85\&s=d30b73c6083cb779b0ff5a82e09085e5)

## How access is structured

A permission is a `resource:action` pair, for example `traces:view` or `datasets:manage`. A role is a named set of permissions. A role binding gives a role to a person, a group or an API key at one scope: the organization, a team or a project.

LangWatch has three scopes:

| Scope | What it contains |
| - | - |
| **Organization** | Billing, members, seats, groups, roles, the audit log and the organization-wide settings |
| **Team** | A set of projects and the people who work on them |
| **Project** | Traces, evaluations, prompts, datasets, API keys and everything else you send data to |

Every member of the organization has an organization role. A role binding at the organization scope applies to every team and project in it, which is how an organization Admin reaches everything. Below that, access to a team or a project comes from a binding on that team or that project.

## Organization roles

Set the organization role per member in **Settings > Users > People**. The role
decides what a person can do at the organization level and how their seat is
counted.

| Role | What it grants |
| - | - |
| **Admin** | Every permission on every team and project in the organization, plus the organization settings: members, teams, roles, groups, billing, the audit log, AI Governance, webhook endpoints and spend data |
| **Member** | `organization:view` and `aiTools:view`. Access to a team or a project comes from a binding on that team or that project |
| **Lite Member** | `organization:view` and `aiTools:view`. On a team or a project a Lite Member is capped at the Viewer permissions below, plus `annotations:create` and `annotations:update`, and never sees costs, the AI Gateway pages or the audit log |
| **Developer** | `organization:view` and `aiTools:view`. Full permissions on their own personal project, and no permission on any shared team or project. An organization-scoped binding or a group binding grants a Developer no permission |

A Lite Member uses a Lite seat, which is counted separately from full seats. In the settings pages a Lite Member can only be given the Viewer role on a team or a project. A group binding above Viewer applies as Viewer for a Lite Member.

A Developer uses a Developer seat, which is counted but never limited. A Developer cannot be given a binding on a shared team, a shared project or the organization; the request is refused naming the seat. Moving a member onto the seat deletes those bindings. The API accepts `DEVELOPER` wherever it accepts an organization role.

**Also check:** [Members and Teams](https://langwatch.ai/docs/platform/members-and-teams.md) for seats, invites and how to change a member's role.

## Team roles

A team role applies to one team and, through inheritance, to every project in it. A binding on a single project adds access on that project only, and never removes what the team role already grants. The built-in roles are **Admin**, **Member** and **Viewer**.

| Resource | Viewer | Member | Admin |
| - | - | - | - |
| `project` | view | view, create, update | manage |
| `team` | view | view | manage |
| `analytics` | view | manage | manage |
| `cost` | | view | view |
| `traces` | view | view, create, update, share | view, create, update, share |
| `annotations` | view | manage | manage |
| `evaluations` | view | manage | manage |
| `datasets` | view | manage | manage |
| `experiments` | view | manage | manage |
| `scenarios` | view | manage | manage |
| `workflows` | view | manage | manage |
| `prompts` | view | manage | manage |
| `triggers` | | manage | manage |
| `secrets` | view | manage | manage |
| `langy` | | view, create, update, delete | manage |
| `agentCache` | | manage | manage |
| `auditLog` | | | view |
| `virtualKeys` | view | view, create, update, rotate | manage, viewOtherPersonal |
| `gatewayBudgets` | view | view | manage |
| `gatewayProviders` | view | view | manage |
| `routingPolicies` | view | view | manage |
| `gatewayGuardrails` | view | view | manage |
| `gatewayCacheRules` | view | view | manage |
| `gatewayUsage` | view | view | view |
| `gatewayLogs` | view | view | view |

A Viewer reads. A Member creates and edits project work, sees costs, and manages its own virtual keys. An Admin also manages the team, deletes projects, and manages the AI Gateway configuration.

## Actions

| Action | Meaning |
| - | - |
| `view` | Read the resource |
| `create` | Create a new one |
| `update` | Edit an existing one |
| `delete` | Delete one |
| `manage` | Implies `view`, `create`, `update`, `delete`, `rotate`, `attach` and `detach` on the same resource |
| `share` | Create a public share link for a trace |
| `rotate` | Rotate a virtual key |
| `attach`, `detach` | Attach a guardrail to a virtual key, or detach it |
| `viewOtherPersonal` | See the personal virtual keys of other members, for off-boarding |

`share` and `viewOtherPersonal` are never implied by `manage`. Grant them explicitly.

## Resources

Each table lists the actions a resource accepts. Resources marked **organization only** can only be granted by an organization-scoped binding; a team or project binding never grants them, even through a custom role that lists them.

### Core

| Resource | Actions | Scope |
| - | - | - |
| `organization` | view, manage, delete | organization only |
| `sso` | view, manage | organization only |
| `team` | view, manage | any |
| `project` | view, create, update, delete, manage | any |

### Product

| Resource | Actions |
| - | - |
| `analytics` | view, create, update, delete, manage |
| `cost` | view |
| `traces` | view, create, update, share |
| `scenarios` | view, create, update, delete, manage |
| `annotations` | view, create, update, delete, manage |
| `evaluations` | view, create, update, delete, manage |
| `experiments` | view, create, update, delete, manage |
| `datasets` | view, create, update, delete, manage |
| `triggers` | view, create, update, delete, manage |
| `workflows` | view, create, update, delete, manage |
| `prompts` | view, create, update, delete, manage |
| `secrets` | view, create, update, delete, manage |
| `langy` | view, create, update, delete, manage |
| `agentCache` | view, manage |

### Platform

| Resource | Actions |
| - | - |
| `auditLog` | view |

### LangWatch AI Gateway

| Resource | Actions | Scope |
| - | - | - |
| `virtualKeys` | view, create, update, delete, rotate, manage, viewOtherPersonal | any |
| `gatewayBudgets` | view, create, update, delete, manage | any |
| `gatewayProviders` | view, update, manage | any |
| `routingPolicies` | view, manage | any |
| `gatewayGuardrails` | view, attach, detach, manage | any |
| `gatewayCacheRules` | view, create, update, delete, manage | any |
| `gatewayUsage` | view | any |
| `gatewayLogs` | view | any |
| `gatewaySpend` | view, manage | organization only |
| `webhookEndpoints` | view, manage | organization only |

### AI Governance

| Resource | Actions | Scope |
| - | - | - |
| `governance` | view, manage | organization only |
| `governanceCost` | view | organization only |
| `ingestionSources` | view, create, update, delete, manage | organization only |
| `anomalyRules` | view, create, update, delete, manage | organization only |
| `complianceExport` | view | organization only |
| `activityMonitor` | view | organization only |
| `aiTools` | view, manage | organization only |

## Custom roles

A custom role is a named permission set you define. Create it at **Settings > Roles & Permissions** with `organization:manage`. Custom roles are Enterprise.

![Settings > Roles & Permissions with the built-in roles and one custom role](https://mintcdn.com/langwatch/MjC98pQzFpMBr6tu/images/platform/roles-list.png?fit=max\&auto=format\&n=MjC98pQzFpMBr6tu\&q=85\&s=8c4405f6151581eff531e8d36aa18c1a)

A custom role has:

| Field | Rule |
| - | - |
| Name | Required, 1 to 50 characters, unique in the organization |
| Description | Optional |
| Permissions | One or more `resource:action` pairs |

Expand a permission category and choose **None**, **Read** or **Full access**
for each resource. Some resources only support Read. The preview explains what
the role permits at the selected scope. Select **Create role** to save it.

![The Create Role dialog with the permission selector](https://mintcdn.com/langwatch/MjC98pQzFpMBr6tu/images/platform/roles-create-permissions.png?fit=max\&auto=format\&n=MjC98pQzFpMBr6tu\&q=85\&s=7996f5a53e4ca280fdcce7b0e4c3f23f)

The permission picker groups resources by product area. The [Roles API](https://langwatch.ai/docs/api-reference/roles/overview.md) accepts every resource and action in the tables above.

To assign a custom role directly, open **Settings > Users > People** and edit the
person's access, or open **Settings > Users > Teams & projects** and add access to a team or
project. You can also choose a role while creating an invite, or assign the
role to a group in **Settings > Users > Groups**. A custom role can be assigned at
organization, team or project scope.

An organization Admin who also holds a
custom team role keeps the Admin access.

## Role assignments

The API calls this a grant (formerly a role binding). In the product, a role
assignment is one row: who, which role and which scope. See [Roles & access](https://langwatch.ai/docs/platform/roles-and-access.md).

| Part | Options |
| - | - |
| Who | A user, a group, or an API key |
| Role | Admin, Member, Viewer, or a custom role |
| Scope | The organization, one team, or one project |

You create role assignments for users from **Settings > Users > People** and
**Settings > Users > Teams & projects**, and for groups from **Settings > Users > Groups**. Open
**Roles**, then choose **Role assignments** to list every assignment in the
organization. Filter it by organization, team or project scope. This tab is
read only.

![Settings > Role Bindings listing bindings per person and group](https://mintcdn.com/langwatch/MjC98pQzFpMBr6tu/images/platform/role-bindings.png?fit=max\&auto=format\&n=MjC98pQzFpMBr6tu\&q=85\&s=4720fb3a90443123a33dc6baaac3dc61)

An API key can hold bindings too. A key with restricted permissions stores its scopes as bindings on the key, and LangWatch intersects them with the permissions of the user who owns the key on every request. A key never grants more than its owner holds at that moment. A service key with no owner has no such ceiling. When a key creates or edits another key, a key can grant at most what the key making the request holds.

**Also check:** [API Keys](https://langwatch.ai/docs/platform/api-keys.md) for how to scope a key.

## Groups

A group gives the same assignments to many people at once. Create a group at
**Settings > Users > Groups** (Enterprise), add members, and assign roles at any
scope. An assignment on a group applies to every member of the group, and the
People tab shows it as "via" the group.

A group synced from your identity provider through SCIM keeps its name and membership under the identity provider's control: you bind roles to it in LangWatch, and the identity provider decides who is in it.

![Settings > Groups with one manual group, its access and its member count](https://mintcdn.com/langwatch/MjC98pQzFpMBr6tu/images/platform/groups-list.png?fit=max\&auto=format\&n=MjC98pQzFpMBr6tu\&q=85\&s=7fa6ffe0e6a5e5c159fa8181a2735a8a)

**Also check:** [SCIM Groups](https://langwatch.ai/docs/platform/scim-groups.md).

## How a request is authorized

LangWatch first checks that the caller is an active member of the organization; a disabled member is refused, and API keys skip this check. It then collects every binding on the scope chain of the request, the project, its team and the organization, including bindings held through groups.

Any binding that grants the permission allows the request; a narrower binding never cancels a wider one. An organization-scoped Admin binding grants every permission. At organization scope, every active member holds the Member organization permissions. Organization-only resources need an organization-scoped binding.


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