Roles
A role is a named set of permissions. Assigning a role to a member grants them every permission it contains. Roles exist at three tiers — organization, workspace, and project — and each tier ships the same four built-in roles, from most to least access:| Role | Typical access |
|---|---|
owner | Full control of the tier, including deleting it. |
admin | Manage configuration and members; includes production trace access. |
developer | Read and change configuration; non-production trace access. |
viewer (member at the organization tier) | Read-only access. |
org_developer who is also a project_admin on one project has admin access there and developer access elsewhere.
Assigning roles. Set a person’s organization role when you invite them, and adjust roles — including per-workspace and per-project roles — from the Team page. Changing someone’s role grants every capability the new role carries.
Custom roles. When the built-in roles don’t fit, you can define a custom role at the organization, workspace, or project tier with exactly the permissions you choose, then assign it like any built-in role.
The permission catalog
Permissions are scoped to the level they act on. The catalog spans, among others:| Area | Examples |
|---|---|
| Organization | Create, read, update, delete organizations |
| Workspace | Create, read, update, delete workspaces |
| Project | Manage projects, labels, and environments |
| Members & invites | List members, manage members, manage invitations |
| Routing | Read, write, publish, review, and roll back routing |
| Providers | Edit configuration, rotate credentials, approve changes |
| Prompts | Read, create, update, publish, and review prompts |
| Environments | Manage environments and environment policies |
| API keys | Create, list, rotate, revoke keys |
| Traces | Read traces, read production traces |
| Audit | Read and export the audit log |
Per-user overrides
Beyond roles, a specific permission can be granted to or removed from an individual member with an override, scoped to the organization, a workspace, or a project. An override can also be set to expire. Use an override for the exception that doesn’t justify a new role: granting one person a single extra capability, or denying one capability someone’s role would otherwise include. A deny override always wins over a grant — whether the grant comes from a role or another override — so you can carve out an exception without rebuilding the role. Reach for a custom role instead when the same exception applies to several people.Trace access
Reading traces is gated by two independently grantable permissions. Production traces — those captured in environments flaggedis_production = true — sit behind a permission distinct from the one that grants access to non-production traces.
| Permission | Scope | Grants |
|---|---|---|
traces:read | Project | Read traces from environments where is_production = false. |
traces:read:prod | Project | Read traces from environments where is_production = true. |
traces:read:prod does not imply traces:read — they are independently grantable, which matters for API keys scoped to a single ingestion path.
Which roles hold which permission
There is no dedicated prod-trace-reader role; the two permissions cascade onto the existing tier roles.| Tier | Role | traces:read | traces:read:prod |
|---|---|---|---|
| Organization | org_owner / org_admin | Y | Y |
| Organization | org_developer | Y | |
| Organization | org_member | ||
| Workspace | workspace_owner / workspace_admin | Y | Y |
| Workspace | workspace_developer | Y | |
| Workspace | workspace_viewer | ||
| Project | project_owner / project_admin | Y | Y |
| Project | project_developer | Y | |
| Project | project_viewer |
org_member hold neither.
Capture-time classification
A trace’s production / non-production classification is fixed when the trace is written, from the originating environment’sis_production flag at that moment. Flipping the environment’s flag later does not re-classify historical traces. This preserves audit determinism.
A user who opens a production trace without traces:read:prod sees an explicit boundary state naming the missing permission — not a generic 404 — so they can request access. Trace IDs from other projects return a generic not-found, so the boundary state can’t be used to enumerate traces across projects.
Granting production trace access
You needorg_admin (or higher) in the organization, and the project must have at least one environment flagged is_production = true.
- To a teammate — on the Team page, open the principal’s role popover at the relevant tier and assign a role that carries
traces:read:prod. Note that changing the role grants every capability the new role carries, not just the trace permission. - To an API key — create or edit a key (see API keys) and select the trace scopes you need.
traces:read:prodalone is a legal scope and is the right choice for a key that only reads production traffic. Issue prod-trace access on a dedicated key and rotate it independently rather than adding it to a multi-purpose ingestion key. - To revoke — change the user’s role to one without
traces:read:prod, or remove the scope from (or revoke) the API key. The change takes effect on the principal’s next request.
traces:read or traces:read:prod is recorded for accountability.
Next steps
Team
Assign roles to people.
API keys
Scope programmatic access.