403 workspace_key_required: call a team Format with a team key

A 403 workspace_key_required means you called a Format owned by a team workspace with a personal API key. Being a member of the team is not enough: create an API key in that team's workspace and use it instead. The error's details.workspace_id names the workspace to create it in.

The rules are from Create a run and Errors and spend, read 2026-09-29.

What does the error look like?

The docs show this body. The workspace id is elided there; yours carries the real one.

{
  "error": {
    "code": "workspace_key_required",
    "message": "This Format belongs to a team workspace. Create an API key in that workspace and use it instead of a personal key.",
    "details": { "workspace_id": "org_…" }
  }
}

Why does Sume require a team key?

The docs say the rule follows the money. A team Format's runs bill the team wallet, count against the team's generation concurrency, and read their media back through the team workspace. A personal key would split those. The docs add that this split used to produce runs that made a real video and then reported output_schema_unsatisfied with nothing harvested.

Personal keys stay right for personal Formats. Create the team key from the team's dashboard.

In practice this means a script that worked against your own Formats can start failing the day you point it at a team's Format, even though you are a member. The script is not broken and neither is your access; the key simply belongs to the wrong workspace for that call.

What if the Format belongs to another team?

A team key from a different workspace is judged by the grant instead: it runs when that workspace holds an accepted grant, and is a 404 format_not_found when it does not. So 403 workspace_key_required always means the right team but the wrong key. Sharing a Format with another workspace covers grants.

How do I fix it?

The fix is a new key, not a retry. Nothing about the request body is wrong, so resending it with the same personal key returns the same error every time. Work through these steps in order, and stop as soon as the call returns a 202 receipt.

• Create a key from the team workspace's API keys dashboard, with formats:read and formats:write.
• Replace SUME_API_KEY in your server's secret store with the new key. Keep it server-side.
• Send the same call again. A failed create releases its Idempotency-Key, so the same key and body can be reused.
• If the error changes to 403 insufficient_scope, the new key is missing a scope; see API keys, scopes and hosts.