bugwatch docs

Tokens & scopes

For agents: whoami() shows your scopes. list_tokens(org="acme") and revoke_token(org="acme", id="…") need org:admin. There is no tool to create a token, and there is no way to do it with the one you hold either: POST /v1/orgs/{org}/tokens refuses bearer-token callers with 403. A human creates tokens in Settings → API tokens.

Tokens

API tokens are organization-bound bearer credentials with an explicit scope list and an optional expiry (1–365 days). The raw value (bwt_ + 48 hex) is shown exactly once; only its SHA-256 is stored. Tokens record last_used_at on every request and can be revoked instantly (DELETE /v1/orgs/{org}/tokens/{id}). A token created by a user carries that user id, so audit rows show both the token name and the person behind it.

Send it as Authorization: Bearer bwt_… to the REST API, the MCP endpoint, and sentry-cli (SENTRY_AUTH_TOKEN).

Scopes

Scope Grants
org:read Read org-level data: members, releases, channels, alert rules, usage, plan catalog, agent activity, docs
org:admin Everything, plus add/remove members, list/revoke tokens, toggle overage. Not minting tokens or Stripe checkout/portal — those need a signed-in user, whatever scope the token carries
project:read List projects, read project settings and DSN keys
project:write Create/update projects, inbound filters, store-IP flag; create and enable/disable DSN keys
event:read Issues, events, fix context, activity, stats, performance, release health
event:write Change issue status (resolve, ignore, reopen, bulk)
release:write Create releases and deploys; upload artifact bundles (native and sentry-cli)
alert:write Create/delete channels; create/update/delete alert rules

Resolution rules, as implemented by hasScope:

  • A scope you hold matches exactly.
  • org:admin implies every scope.
  • A :write scope implies the matching :read: event:write satisfies event:read, project:write satisfies project:read. The reverse never holds.
  • Cross-organization requests return 404, never 403 — existence is not leaked.

Presets

The dashboard offers four presets; they are just scope lists you can also send to POST /v1/orgs/{org}/tokens.

Preset Scopes Use for
Read-only (reader) org:read, project:read, event:read Exploration, get_fix_context, coding agents that only read
Triage (triage) reader + event:write Agents allowed to resolve / ignore / reopen (audited)
Operator (operator) triage + project:write, release:write, alert:write CI, release scripts, alert setup, key rotation
Admin (admin) org:admin Members, tokens, billing flags — use sparingly

Mint example:

curl -sS https://api.bugwatch.io/v1/orgs/acme/tokens -H 'Authorization: Bearer bwt_<admin>' \
  -H 'content-type: application/json' \
  -d '{"name":"claude-code","scopes":["org:read","project:read","event:read"],"expiresInDays":90}'
# → {"token":"bwt_…","note":"save this now — it is not shown again"}

What agents cannot do

These routes intentionally have no MCP tool, and the parity test fails if one is added without a reason. The first three go further: they check that the caller is a signed-in user, so presenting an org:admin token gets 403 rather than access — otherwise a leaked token could simply mint a replacement and outlive its own revocation.

  • POST /v1/orgs/{org}/tokens — agents must not mint credentials.
  • POST /v1/orgs/{org}/billing/checkout and …/billing/portal — browser redirects to Stripe; purchases and billing-portal sessions stay human-initiated.
  • POST /v1/orgs/{org}/projects/{project}/artifact-bundles — binary upload; use sentry-cli or the endpoint directly.

Auditing

Every mutating tool call is recorded in agent_actions with the token id, user id, tool, arguments (secrets reduced to their kind, capped at 4,000 characters), outcome, HTTP status, and duration; issue-scoped mutations also land in the issue's activity feed. Read-only calls are not recorded. list_agent_activity(org, limit≤200) returns the newest first.

Roles versus tokens

Dashboard users get scopes from their membership role at request time (owner/admin → everything including org:admin; member → everything except org:admin; viewer → org:read, project:read, event:read). Tokens carry their own list and are not affected by the creator's later role changes. See Members & roles.