Skip to main content

​
Grant production trace access

Follow this guide when you need to give a teammate or API key the ability to read production traces in a project they already belong to.

​
Before you start

You need:
  • org_admin (or higher) in the organisation containing the project.
  • The principal you intend to grant — a user or an API key — already exists and either holds a non-prod-capable membership in the project, or you are about to create the API key with the relevant scopes.
  • The project has at least one environment flagged is_production = true. If it does not, follow the environment-policy how-to first; trace classification is sourced from that flag at capture time.

​
Grant to a user

For an existing teammate already a member of the project:
  1. Open the Team page in your organisation: /org/[orgSlug]/settings/team.
  2. Locate the principal in the role matrix. The role columns cover every tier (organisation, workspace, project); the current role at each tier appears in the corresponding column.
  3. Open the role popover for the principal at the tier where you want to grant prod-trace access and select a role that carries traces:read:prod.
The role popover lists the available roles for that tier; the trace permissions each role carries are shown alongside. Roles that carry traces:read:prod:
Roletraces:readtraces:read:prod
project_developerY
project_adminYY
project_ownerYY
workspace_adminYY
workspace_ownerYY
org_adminYY
org_ownerYY
Changing the role grants every capability the new role carries — not just the trace permission. If the principal should hold only the trace permission and nothing else, use an API key with a narrow scope instead (see the next section).

​
Grant to an API key

For machine-to-machine access (ingestion pipelines, scheduled reports, support tooling):
  1. Open the API keys settings page: /settings/api-keys.
  2. Click “Create API key” and step through the wizard.
  3. On the scope step, select the trace permissions you need:
The scope step lists traces:read and traces:read:prod as independent checkboxes; pick the combination that matches the key’s intended use. 
scopes:
  - traces:read
traces:read:prod alone is a legal scope and is the right choice for a key that only reads production traffic.
Do not grant traces:read:prod to an API key used by a multi-purpose ingestion pipeline. Issue a separate key with traces:read:prod and rotate it independently — that way the audit log identifies which path read which traces, and revoking prod access does not interrupt non-prod ingestion.

​
Revoke

To revoke prod-trace access:
  • For a user: open /org/[orgSlug]/settings/team, find the principal in the role matrix, and change their role at the relevant tier to one that does not carry traces:read:prod (for example, project_developer). The change takes effect on the next request the user issues; existing in-flight requests complete under the prior permission set.
  • For an API key: open the API keys settings page, locate the key, and either edit the scope list to remove traces:read:prod or revoke the key entirely. Revoking the key is the safer option if you suspect compromise.
Either path writes a row to the audit log.

​
Verify the grant in the audit log

To confirm a grant or revocation was recorded:
  1. Open the project audit feed: /org/[orgSlug]/ws/[workspaceSlug]/prj/[projectSlug]/audit.
  2. Filter the event type to rbac_grant.
  3. Locate the row matching the principal and timestamp.
Filtered audit-feed rows display the actor, the affected principal, the change to the effective permission set, and the timestamp. The audit row records the actor, the affected principal, the prior effective permission set, the new effective permission set, the scope, and the timestamp. Retention is five years per the platform-wide audit-log policy.

​
Troubleshooting

I granted the role but the user still sees the boundary state. Wait for the next request and refresh; the dashboard may take a few seconds to reflect the new role. If the boundary state persists, verify in the isolation-conformance view that the role cascade is in force. The audit log row does not appear. Confirm the grant actually changed the effective permission set. Granting an already-held permission writes no audit row — the log records effective-set changes, not raw role-assignment events. I want to grant prod-trace access for a fixed window — for example, four hours during an incident. Time-bounded grants are on the Phase 2 roadmap (PRD §Phase 2 item 4). Today the workaround is to grant the role at the start of the window and revoke it at the end; both operations are audited.

​
Next steps

How trace access works

Reference page covering the two permissions, the role cascade, capture-time classification, and the boundary state.

Isolation conformance view

Confirm the cross-store policies are in force on every project-scoped table in your organisation.