How Sume API keys work: scopes, auth headers, hosts, and rotation

A Sume API key is a workspace-scoped secret you create in the API Keys dashboard and send on every request as either Authorization: Bearer or x-api-key, never both. Its scopes are fixed when it is created, and it works only on the host it was created for.

Everything below is from Sume's Authentication and API keys docs, plus the keys and hosts sections of Create a run and the Format API overview.

How do I send a Sume API key?

Keep the key in a server-side environment variable and send it in one of two headers. The API accepts both; use one consistently in each integration. The Sume CLI defaults to x-api-key.

Send exactly one. A request that carries both Authorization: Bearer and x-api-key is rejected with 401 unauthorized and the message Send only one API key credential. Neither header wins. This bites gateways and fetch wrappers that add their own Authorization header on top of a client that already sends x-api-key.

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

# or, never both:
curl https://api.sume.com/v1/me \
  -H "x-api-key: $SUME_API_KEY"

What does the key decide for me?

Sume resolves the workspace, the owner, and the key's metadata from the key itself. Do not put workspace_id, owner_user_id, or user_id in public API request bodies. Responses expose key metadata such as id, name, prefix, scopes, and last-used time, but never the full secret.

The dashboard reveals the full secret only when a key is created, so store it in a secure secret manager right away. Each key also gets its own per-minute request budget, set by the workspace's plan; see Sume API errors and rate limits.

Which scopes does a key need?

Scopes are fixed when a key is created and cannot be added later. A key created before a scope existed does not carry it, and there is no API to patch scopes onto an existing key: create a new key and rotate to it.

• A key missing a Formats scope fails every Format request with 403 insufficient_scope, never 404 format_not_found.
• An older key without the Actions scopes returns 403 insufficient_scope on every Action run request.
• Service-account keys cannot create Format runs. They fail with 403 insufficient_scope and a details.reason of service_account_format_runs_unsupported.

What do 401, 403, and 404 say about my key?

Branch on the HTTP status first and error.code second. A 403 workspace_key_required means right team, wrong key: a team Format is invoked with a key created in that team's workspace, membership is not enough, and details.workspace_id names the workspace to create the key in. The rule follows the money, because a team Format's runs bill the team wallet and count against the team's generation concurrency.

Which host does my key work on?

Production is https://api.sume.com: runs there spend real credits from your workspace, and keys come from the API keys dashboard. Sume also runs a separate development host for integration and staging, with the same routes, receipts, and webhook delivery. Its keys are issued for a development workspace; ask your Sume contact.

• A key works only on the host it was created for. The other host answers 401 unauthorized.
• Keys for both hosts look like sume_live_…, so name your environment variables by host rather than by prefix.

How do I rotate a key and keep it safe?

Create a replacement key, deploy it to your server, verify it with GET /v1/me, then revoke the old key from the dashboard. Rotate any key that appears in logs or chat history.

• Keep keys on trusted servers, in CI secret stores, or on local developer machines.
• Do not place keys in frontend JavaScript, mobile apps, support tickets, or screenshots. Browser and mobile clients should call your backend, which validates input, enforces your own authorization, and attaches the key.
• Give agents read-only commands first, and require explicit confirmation before write or paid generation commands.