Sume API key scopes per call: formats, jobs, account, webhooks

Sume API keys carry scopes that are fixed when the key is created, and a call without the right scope gets 403 insufficient_scope. Reads of Format runs need formats:read, cancel and redeliver need formats:write, and reading the webhook signing secret needs account:read.

You cannot add a scope to an existing key: there is no API to patch scopes onto a key, so an old key that predates a scope has to be replaced.

Which call needs which scope

Collected from the Sume authentication, webhook and Format run pages (read 2026-10-03).

The old-key trap

Keys created before a scope existed do not carry it. A pre-Formats key calling a Format gets 403 insufficient_scope, never 404 format_not_found, and a key older than the Actions API trigger returns 403 insufficient_scope on every Action run request. The fix is to create a new key and rotate to it.

Check what a key carries before you rely on it. GET /v1/me verifies the key and the workspace it resolves to, and responses expose key metadata such as id, name, prefix, scopes and last-used time, but never the full secret.

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

A least-privilege layout

Give the service that only reads dashboards a key with read scopes, give the receiver that redelivers webhooks jobs:write or formats:write, and keep account:write for the operator who rotates the signing secret. Separate keys also help with the job visibility rule: an API key reads only jobs its own member created, as in why a job returns 404. For a service-account failure, see 403 insufficient_scope on a Format run.