Access Control (RBAC)

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

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 refuses calls without one with HTTP 402 and the error code enterprise_plan_required. To enable it, contact [e-mail].

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

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

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 permission picker groups resources by product area. The Roles API accepts every resource and action in the tables above.

To assign a custom role directly, open Settings > Directory > People and edit the person’s access, or open Settings > Directory > 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 > Directory > 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.

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 > Directory > People and Settings > Directory > Teams & projects, and for groups from Settings > Directory > 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.

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 for how to scope a key.

Groups

A group gives the same assignments to many people at once. Create a group at Settings > Directory > 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.

Also check: SCIM Groups.

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.