Service-account key gets 403 on a Format run: use a user or team key

If a Format run fails with 403 insufficient_scope and details.reason of service_account_format_runs_unsupported, the key is a service-account key. The Format docs say these keys cannot create Format runs. Create a user key with the formats:read and formats:write scopes instead, or a team-workspace key if the Format belongs to a team.

The 403 family

The Format API separates three 403 and 404 cases that look alike. Read error.code and details.

Fixing it

Open API keys in the dashboard, create a key in the workspace that owns the Format, and tick the Formats scopes. Keys made before the Formats API shipped do not carry those scopes and fail every Format call with 403 insufficient_scope, never a 404. Rotate to the new key; you cannot patch scopes onto an old one.

Keep the key server-side and store it as a secret. If your automation runs under a service account for other Sume calls, give the Formats job its own key and its own variable so the two do not get mixed up.

• One key per purpose, with only the scopes needed.
• For a team Format the key must come from the team workspace.
• Membership alone does not stand in for a team key.

Auditing your keys

List the keys your automation uses and write down which scopes each carries. Mixed scopes are the usual cause of this class of error: a key that works for media jobs but was minted before the Formats scopes existed. A short inventory, with the workspace each key belongs to, answers most 403 questions in a minute.

Limits

This is the documented behaviour of the Format run endpoints; other Sume endpoints may treat service accounts differently, and the Agent Completions docs separately say service accounts are refused there. Check each page before you plan around it. A 401 is a different problem: no key, a malformed key, two credentials at once, or a revoked key.