Permission scopes

API-key scopes use resource:action. A key can receive only known scopes held by the member creating it. Project scope and permission scope are both enforced: neither can widen the other.

The authenticated scope catalog at GET /api/v1/account/api-keys/scopes and Settings → Access is authoritative. The groups below describe the current selectable catalog.

Telemetry and investigation

Resource	Scopes
Ingestion	ingest:write
Traces	traces:read, traces:delete
Logs	logs:read, logs:delete
Metrics	metrics:read, metrics:delete
Errors and Issues	errors:read, errors:write, errors:delete
Query and search	query:read, query:write, search:read
Saved searches	saved_search:read, saved_search:write, saved_search:delete
Customers and accounts	persons:read, groups:read, groups:write, groups:delete
Events and flags	analytics:read, analytics:write, flags:read, flags:write, flags:delete
Anomalies	anomalies:read, anomalies:write, anomalies:delete
Replay	replay:read, replay:write, replay:delete
Releases	releases:read, releases:write
Export	export:read, export:write, export:download (owner/admin only)

errors:write allows Issue lifecycle actions and symbol uploads; deleting error data requires errors:delete. Application SDKs use ingest:write for OTLP telemetry and captured errors, plus analytics:write when sending diagnostic, identify, group, or screen events through the capture surface. Session replay uses replay:write instead of ingest:write.

Response and collaboration

Resource	Scopes
Alerts	alerts:read, alerts:acknowledge, alerts:resolve, alerts:rules:read, alerts:rules:write, alerts:rules:delete
Silences	silences:read, silences:write, silences:delete
Delivery channels	channels:read, channels:write, channels:delete
On-call	oncall:read, oncall:contacts:write, oncall:write, oncall:delete
Escalation	escalation:read, escalation:write, escalation:delete
Incidents	incidents:read, incidents:respond, incidents:write, incidents:delete
Dashboards	dashboard:read, dashboard:write, dashboard:delete
Connections and tickets	connections:read, connections:write, connections:delete, tickets:read, tickets:write, tickets:delete
Account segments	account_segments:read, account_segments:write, account_segments:delete

Responder actions such as acknowledging an alert or appending to an incident are separate from configuration and deletion. Give on-call automation the responder scopes it needs, not blanket administration.

Treat channels:read as a credential-grade scope. Reading a delivery channel returns its stored configuration as you saved it, and a webhook channel’s configuration includes its URL and any request headers you attached — which is where an authorization token usually lives. A key that only needs to send telemetry should not carry it. Sending a test notification is channels:write, not channels:read, because it delivers a real message to that channel’s recipients; a key used for test-sends needs both, since the test first reads the channel it is about to use.

Personal contact methods are self-service and are gated twice. oncall:read lists them and oncall:contacts:write adds, edits, or removes them; separately, every request is confined to the calling user’s own contact methods, so no key can read or change someone else’s. Both scopes are available to every role, including viewers — being reachable when you are on a rotation does not depend on your role. Note that an API key acts as the member who created it, so a key you did not intend to use for this still needs oncall:contacts:write withheld to be unable to change that member’s paging destinations. Schedule administration stays on oncall:write and oncall:delete.

For dashboards, dashboard:write permits creation, cloning, and widget or layout changes. Changing dashboard metadata or variables is limited to the dashboard owner and organization admins, and deletion requires both dashboard:delete and dashboard-owner or organization-admin status. dashboard:read never makes a shared URL public; dashboard links still require an authenticated same-organization principal.

Organization, AI, and agents

Resource	Scopes
Settings	settings:read, settings:write, settings:delete
GitHub configuration	github_config:read, github_config:write
Projects and members	projects:read, projects:write, projects:delete, members:read, members:write
API keys	api_key:read, api_key:write
Scores and evaluations	scores:read, scores:write, evals:read, evals:write
Customer Detective	investigations:run
Usage	usage:read
MCP	mcp:read, mcp:write

Settings permissions are deliberately separate. settings:read shows stored organization and global LLM pricing overrides without edit controls; it does not expose the embedded fallback catalog. Adding or editing an organization override requires settings:write, and deleting one requires settings:delete.

The same three scopes cover the organization record and its configuration entries. Reading the organization or its configuration requires settings:read; renaming the organization or writing a configuration entry requires settings:write; deleting the organization or removing a configuration entry requires settings:delete. A key holding none of them authenticates normally and receives 403 permission_denied on all of them — which is the point: an unscoped key must not be able to delete your organization. Changing a plan or a usage limit is not available to any organization role, including owner.

Listing projects and listing the member roster are reads in their own right: projects:read returns each project’s name, slug, id, and retention — whether you list them all or fetch one by id — and some endpoints need it indirectly, because exporting data validates the project you name before it accepts the job. members:read returns the roster including pending invitations, which are the not-yet-accepted half of the same list. Both are available to every role, because the project selector and the member picker appear throughout the product; creating, renaming, or deleting a project, and administering members or invitations, remain owner/admin-only under projects:write, projects:delete, and members:write. A key without the read scopes authenticates normally and receives 403 permission_denied on those endpoints, so an ingestion-only credential cannot enumerate your projects or your people.

Key management is itself scoped. Listing the organization’s keys requires api_key:read, and creating, renaming, revoking, or re-scoping one requires api_key:write. A key without them authenticates normally but receives 403 permission_denied on those endpoints — listing exposes every key’s id, name, and granted scopes, so it is not something an unscoped credential should reach. Granting api_key:write does not widen a key: a new key can still only receive scopes its creator already holds. Leave both off any key that does not administer credentials.

mcp:write is an umbrella gate. An MCP write also requires its domain scope. For example, creating an incident requires both MCP write access and the incident permission enforced by that tool. Exact telemetry deletion requires mcp:write plus traces:delete or logs:delete on a project-scoped key; the MCP actions do not accept a project override.

Safe key patterns

• Browser or mobile SDK: project-scoped ingest:write plus analytics:write; add replay:write only when recording browser replay. Browser flag evaluation additionally needs flags:read; treat all flag configuration and payloads as client-visible.
• Server SDK: project-scoped ingest:write, adding analytics:write when it calls identify, group, screen, or diagnostic-event methods.
• OpenTelemetry collector: project-scoped ingest:write only.
• Read-only agent: mcp:read and only the read domains it needs.
• Telemetry-cleanup agent: dedicated project key with mcp:write and only traces:delete and/or logs:delete; both actions preview the signed project and exact target before confirmation.
• CI symbol upload: dedicated project key with errors:write; add releases:write when the same job also registers a release.
• Operations automation: explicit responder or configuration scopes, fixed project, no unrelated deletes.

The wildcard platform-admin permission is not grantable to API keys.

• Authentication and API keys
• Permissions and safe actions