Sume Action run 403 insufficient_scope: old keys and service accounts

A 403 insufficient_scope on POST /v1/actions/{action_id}/runs means the API key has no actions:write (or actions:read), or it is a service-account key. Scopes cannot be added to an existing key, so the fix is a new key from the dashboard.

The details are in Advanced: run a schedule via API. The error body names the cause in details.

Which scopes does a run need?

Scopes are checked per call, so a key can list schedules fine and still fail on the run request. A key with only actions:read can call GET /v1/actions and GET /v1/action-runs/{id}, but POST .../runs and POST .../cancel need actions:write. If your monitoring job only reads, give it a read-only key and keep the write key to the service that triggers runs; that is the narrowest setup the scopes allow.

Why does an old key fail?

Keys created before the API-call trigger shipped do not carry the Action scopes. Such a key fails every run request with 403 insufficient_scope, and details.required_scope is actions:write. Agent Completions has the same history with its own scopes. Because scopes cannot be added to a key after creation, create a new key at the API Keys page and rotate to it.

Rotation is straightforward: create the new key with the scopes you need, deploy it to the caller, confirm a run starts, then revoke the old key. Do not paste keys into logs; safe logs per the docs hold request ids, job ids and high-level status, and unsafe ones hold API keys and signed URLs. See Authentication for how keys are created and sent.

What about service-account keys?

Service-account keys cannot create Action runs at all. They fail with 403 insufficient_scope and details.reason of service_account_action_runs_unsupported. The fix is a key created for a user in the dashboard. Agent Completions has the parallel reason service_account_agent_completions_unsupported.

How do I tell the causes apart?

Read error.details rather than the message. The envelope also marks insufficient_scope as category: "auth" with next_action: "authenticate": the cause is the key, not the request body, so do not retry the same call.

Also remember that actions owned by a team workspace are not reachable over the public API yet, by either the opaque or vanity path. A key that is otherwise right can still get 404 action_not_found for that reason.

For comparison with the Format side, the same service-account restriction applies to Format runs, covered in Format run 403 for a service-account key. If you generate a client from OpenAPI, note that the invoke route declares 403, so model it and surface details.reason to whoever has to fix the key.

curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}' | jq '.error | {code, details, request_id}'