Agent Completions 403 insufficient_scope: old key or service account?
A 403 insufficient_scope on POST /v1/agent/completions has two causes: a key made before the feature, or a service-account key. details.reason tells which.
A 403 insufficient_scope from POST /v1/agent/completions has two documented causes. Either the key was created before Agent Completions shipped and lacks the agent_completions:* scopes, or it is a service-account key. Look at details.reason: service-account keys return service_account_agent_completions_unsupported.
Cause one: an old key
The Agent Completions docs say keys created before the feature shipped do not have agent_completions:read or agent_completions:write. You cannot add scopes to an existing key. Create a new key in the dashboard, then rotate your service to it.
Cause two: a service-account key
Service-account keys cannot create Agent Completions at all. The request fails with the same 403 insufficient_scope, with the reason string above. The fix is to use a user-owned key. The docs also note that completions are user-owned and that team-owned threads are not available yet.
| Symptom | Likely cause | Fix |
|---|---|---|
| 403 insufficient_scope, no special reason | Key predates the feature | Create a new key with agent_completions scopes; rotate |
| 403 with details.reason service_account_agent_completions_unsupported | Service-account key | Use a user-owned key |
| Read works, create fails | Key has read but not write | Create a key with agent_completions:write |
The same pattern on schedules
Schedule runs have the same shape. The API trigger docs require actions:read and actions:write, say older keys fail with 403 insufficient_scope, and give the service-account reason service_account_action_runs_unsupported. If a team swaps keys while adopting a new model, check which family of scopes the key carries.
Do not confuse it with a model error
New model launches this week, such as Claude Haiku 5.5 on 2026-10-07, tempt people to blame the model for a failing call. A 403 happens before any model runs. And the model field on this endpoint accepts only sume-agent; a different value returns 400 invalid_request, not 403.
Quick check
The points that matter here, in the order you will hit them:
- Print the status,
error.code, anddetails.reason, not just the HTTP status. - Confirm the key was created after the feature shipped.
- Confirm it is not a service-account key.
- Rotate, then retry with a fresh
Idempotency-Keyonly if the payload changed.
Rotation order
Rotate in this order. Create the new key with the scopes you need. Deploy it to the service. Watch for the first successful 202. Only then revoke the old key. Reversing the order gives you an outage window. If a team shares one key between schedules and completions, remember that the two families use different scope names, actions:* and agent_completions:*, so a key made for one does not automatically work for the other.
If the 403 persists after rotating, read the whole error body. The docs list other statuses for this endpoint that look similar at a glance: 400 invalid_request for a missing spend cap or a model other than sume-agent, 404 agent_run_not_found for an unknown run id or a run another account owns, and 409 idempotency_conflict for key reuse with a different payload. An Action or Format run id will not resolve on the agent-runs endpoint, so check that you are polling the family you created.
Sources
Related posts
More in Developers
- Agent Completions model field is sume-agent only: no Haiku or GLM
You cannot choose Claude Haiku 5.5 or GLM 5.3 in the Agent Completions model field. Sume accepts sume-agent and returns 400 for anything else.
- Edit returns a square? A 1-cent test for aspect_ratio auto vs none
Omitting aspect_ratio on a Sume edit is not the same as auto. A 1-cent low-quality regression test that catches the dropped field before it ships.
- API Gateway to Lambda: verify a Sume video webhook on the raw bytes
A Sume callback_url can point at a Lambda behind an HTTP API. Decode the body to bytes first, then verify sume-v1 with the SDK. Handler code is under 30 lines.
- Sume ignores aspect_ratio when image_size is set: Flux, Seedream
On Sume's custom-pixel image rows, image_size wins and aspect_ratio is ignored. Nano Banana turns WxH into an enum ratio. What each model does with both fields.
Written by Sume