API key scopes for Sume: which key can call which endpoint family?

A Sume API key carries scopes that are fixed when the key is created, and each endpoint family checks its own: formats:read and formats:write for Formats, actions:read and actions:write for scheduled Actions, agent_completions:read and agent_completions:write for Agent Completions, and account:read or account:write for webhook signing-secret routes. If a route returns 403 insufficient_scope, the key is missing the scope and the only fix is a new key.

Scope by endpoint family

The table lists the scopes the docs name. Generation endpoints such as /v1/image-1.0/generate and /v1/jobs are not listed with a scope in the reference, so check the live OpenAPI at https://api.sume.com/reference/json for the authoritative list for your version.

Why an older key returns 403

Scopes cannot be added later. A key created before a scope existed does not have it, which matters for actions:*, formats:* and agent_completions:*, all of which shipped after the first keys were issued. The error is 403 insufficient_scope, not a 404, and details.required_scope names the missing one on Formats. Create a new key in the dashboard, deploy it, check it with GET /v1/me, and then revoke the old key.

Two related 403s are not about scopes. A personal key calling a team Format returns 403 workspace_key_required with the workspace id in details, and the fix is a key created in that workspace. And service-account keys cannot create Format runs or Agent Completions at all; the 403 carries a details.reason that says so.

Key hygiene that the docs insist on

• Send exactly one credential. Both Authorization: Bearer and x-api-key on the same request is a 401 unauthorized. The TypeScript SDK sends x-api-key only, so a gateway or interceptor that adds Authorization breaks an otherwise correct call.
• Keep keys on servers. A Sume key spends your credits and has no browser-safe variant. Put your own endpoint in front and attach the key there.
• Do not put workspace or user ids in request bodies. Sume reads the workspace and owner from the key.
• Rotate by overlap: create the replacement, deploy it, verify with GET /v1/me, then revoke the old one. If a key shows up in logs or chat, rotate it.

Choosing scopes when you create a key

The dashboard at API Keys is where keys are made, and the scopes are set at that moment. Decide the job first. A backend that only reads results needs the read scope of the family it reads. A service that starts runs needs the write scope and, because it will want to poll its own receipts, the read scope too. Reads and writes are separate scopes and also separate rate-limit buckets, so a narrow key and a narrow budget travel together.

Because you cannot widen a key, a little foresight saves a rotation. If you know a scheduled Action will later be started over the API, create the key after the Actions API-call trigger shipped and include both Actions scopes now. If a pipeline will eventually read the webhook signing secret from the API instead of a dashboard copy, add account:read when you create the key, not later.

A quick scope audit

GET /v1/me returns the key's metadata, including its scopes, prefix and last-used time, and never the full secret. Run it with each key you plan to use before wiring it into a worker. A thirty-second check beats a production incident in which every scheduled run fails with 403 because the key predates the Actions trigger.

For a service that does several things, use one key per job rather than one key for everything. A webhook-secret reader needs account:read and nothing else, and a Format runner needs formats:write and formats:read. Narrow keys limit what a leaked key can do and make the scope errors easy to read.