Agent Completions 403 insufficient_scope: an older key needs replacing
POST /v1/agent/completions returns 403 insufficient_scope for a key that predates Agent Completions or a service-account key. How to tell which and replace it.
If a new tool call to POST /v1/agent/completions answers 403 insufficient_scope, the key probably predates Agent Completions. Sume's docs say keys created before the feature shipped do not carry agent_completions:read or agent_completions:write, and scopes cannot be added to an existing key. Create a new key in the dashboard, switch your server to it, and retire the old one. A service-account key fails with the same status but a different reason.
Two causes, one status
The Agent Completions page describes both. An older key fails every request with 403 insufficient_scope. A service-account key fails with 403 insufficient_scope too, but details.reason is service_account_agent_completions_unsupported. Read the details object before you rotate anything.
| Signal | Cause | Fix |
|---|---|---|
No details.reason, key is old | Key predates the scopes | Create a new user key |
service_account_agent_completions_unsupported | Service-account key | Use a user-owned key for this endpoint |
MCP insufficient_scope instead | OAuth session without mcp:write | Grant write at consent or use a key |
Rotate safely
- Create the new key at the API keys page in the dashboard and store it in your secret manager under a new name.
- Deploy the new name to the service that hosts your model's tool handler, then send one cheap test with a low cap such as 1 dollar.
- Check that the first receipt is a
202with a run id. - Delete the old key only after traffic has moved, and rotate it immediately if it ever appeared in a log or chat.
The same trap elsewhere
Schedule API runs have the same pattern: keys from before the API-call trigger lack actions:read and actions:write; see Advanced: run a schedule via API. It is worth issuing one new key per integration so scopes are not a surprise later. Authentication covers key creation, and Safe automation covers what to keep out of logs.
Hosted MCP behaves differently: an OAuth token is not a Sume API key, and sume login does not broker MCP tokens, per the MCP OAuth page. Do not mint an API key for an MCP client just to silence a 403; add mcp:write at consent if the task really needs it.
Sources
Related posts
More in Developers
- Cancel an Agent Completion at a deadline: Python poll loop
A Python loop that starts a Sume Agent Completion, polls status_url until next_action stops saying poll_status, and cancels at a deadline.
- Lazy-load placeholder for an AI image: average color from Sume
Compute the average color of a generated image with Pillow, use it as the background of the image box and avoid a white flash while the real file loads.
- Prompt length limits across Firefly and Sume
Adobe Firefly now takes longer prompts for Image and Video on the web. Sume documents a 5000-character cap for music and no stated cap elsewhere.
- AI image prompt regression test: check size, ratio and alpha in CI
Before you swap or upgrade an image model, run a fixed prompt set through Sume and assert pixel size, aspect ratio and alpha with Pillow. Python test included.
Written by Sume