Keys and scopes

Embed
Preview of the card
<a href="https://watchtowerops.net/docs/keys-and-scopes"><img src="https://watchtowerops.net/docs/_api/public/orgs/aa5959cb-1a0b-4a9a-bc9a-913e7ac31cd9/spaces/b7aac181-9916-4805-b253-becc5fd2ca62/pages/0e6d8c12-a7c6-4302-a85a-eec2ea847919/social-card.svg?v=3e7ae33eec8b" alt="Keys and scopes" width="600" height="315"></a>

Watchtower has five kinds of key. They differ in who holds them, what they can reach and how scopes apply.

Kind

Prefix

Created with

Who it acts as

Scopes

Personal access token (PAT)

wtu_

POST /v1/me/tokens

You, optionally narrowed

Optional list; omit for your full role

Org API key

wtk_

POST /v1/orgs/{org}/api-keys

A role in the org or one project

None: a role, optional read_only, optional allowed_cidrs

Service account key

wta_

POST /v1/orgs/{org}/service-accounts/{id}/keys

The service account's role

Required, non-empty

Ingest key

wti_

POST /v1/projects/{prj}/credentials

One project and environment

Required, ingest:* and a few agent scopes

Publishable key

wtp_

POST /v1/projects/{prj}/rum/keys

The browser SDK of listed origins

Always ingest:rum (fixed)

Scope table

A cell with a mark means the kind can carry that scope.

Scope

PAT

Org API key

Service account key

Ingest key

Publishable key

ingest:traces

yes

yes

ingest:logs

yes

yes

ingest:metrics

yes

yes

ingest:errors

yes

yes

ingest:alerts

yes

yes

ingest:checkins

yes

yes

ingest:rum

yes

yes (fixed)

ingest:profiles

yes

ingest:feedback

yes

ingest:activity, read:activity, test:activity

yes

agent:fleet

yes

probes:read

yes

query:read

yes

yes

query:sql (implies query:read)

yes

yes

admin:read

yes

yes

admin:write (implies admin:read)

yes

yes

ci:write

yes

yes

(no scopes: role decides)

yes

Notes:

  • A PAT accepts the same list as a service account key, but only the query:*, admin:* and ci:write scopes do anything on the API. Omit scopes to keep your whole role.

  • The ingest:* scopes are for the telemetry endpoints (ingest.<host>); an API-scope key cannot send telemetry and an ingest key cannot call the API. A key without the scope for a route gets 403 only for resources it can see; resources it cannot see stay 404.

  • ingest:rum credentials and agent:fleet keys are never browser keys; the publishable key is the only one meant to be public (it is bound to an origin allowlist).

  • A project-scoped org API key with read_only answers 403 read_only_key to anything but GET and HEAD.

ci:write

ci:write is the scope for a CI job. It is deliberately narrow: it covers only these routes under /v1/projects/{prj}/:

Methods

Path prefix

Use

GET

releases, deployments, environments

Read back what CI tools check before they write

POST, PUT, PATCH

releases

Create and update releases, attach commits

POST, PUT, PATCH

deployments

Deploy markers

POST, PUT, PATCH

test-runs

Test visibility results

POST, PUT, PATCH

artifacts

Source map and other build artifact uploads

POST, PUT, PATCH

sentry

Sentry-CLI compatible release and source map uploads

Everything else is refused: no reads of telemetry, no DELETE (so a CI key cannot delete a release), no audit routes, no other configuration. This is the scope to put in WT_API_KEY for wtctl release, the deploy-marker call, and the source map upload of the bundler plugins and withWatchtower.

Create a service account key

All three fields are required; a request that misses some answers one 422 that lists every missing field.

curl -sS -X POST "$WT_API/v1/orgs/$ORG/service-accounts/$SA/keys" \
  -H "Authorization: Bearer $WT_PAT" -H "Content-Type: application/json" \
  -d '{"name":"storefront-ci","expires_in_days":365,"scopes":["ci:write"]}'

The response carries the key once (wta_...); only its SHA-256 hash is stored. Scope presets for the common cases (ci, ingest-all, read-only, query-readonly, sql-analyst) are listed by GET /v1/orgs/{org}/key-presets.

Updated