Team Format returns 403 workspace_key_required: which key to mint

403 workspace_key_required means you called a team Format with a personal API key. Create a key in the team workspace named in error.details.workspace_id and call again. Team membership alone is not enough: the run bills the team wallet and counts against the team's generation concurrency, so the key must come from that workspace.

What the error looks like

The body is a normal error envelope with code: workspace_key_required and a message that says to create a key in that workspace. details.workspace_id holds the org id. The status class is the first branch and the code is the second, so a script can switch on the code.

Which answer you get

The answer depends on who you are and what key you used. The table is from the Create a run docs, as of 2026-10-09.

Steps to fix it

Follow these in order.

• Open the team workspace's dashboard and create an API key there. Scopes are fixed when a key is minted, so a key made before the Formats API will lack formats:read and formats:write; make a new one.
• Use the key for the same POST /v1/formats/{handle}/{slug}/runs call. Keep the team handle in the path.
• Do not use a service-account key for run creation: it fails with 403 insufficient_scope and details.reason set to service_account_format_runs_unsupported.
• Keep personal Formats on personal keys; they stay correct there.

Why the 404 exists

A Format that someone else owns answers 404 by design, so the API does not show that the Format exists at that address. For that reason, a 403 workspace_key_required always means the right team and the wrong key.

Why the rule is the way it is

The docs explain the reason. 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 can split those three, and in the past a personal key produced runs that made a real video and then reported output_schema_unsatisfied with nothing harvested. The 403 stops that case at the door.

A practical habit: keep one key per workspace and name them so you can tell them apart in your secret store, for example by the team handle. Rotate by creating the new key first, switching your service, and then revoking the old one. Reads follow the same rule: a team key lists the Formats of that workspace for every member and never your personal Formats.

If you are not sure which workspace a key belongs to, call a read such as GET /v1/formats with it and look at which Formats come back. A team key lists that workspace's Formats, and a personal key lists your personal ones. That is a quick test before you spend time on a run, and it costs nothing.