Which API key scopes does a Sume webhook receiver need?

A webhook receiver needs no Sume API key to verify a delivery, only the signing secret. The key scopes come in when you operate the webhook: account:read to read the secret, account:write to rotate it or send a test delivery, and jobs:write to redeliver a real job.

That gives you a clean split for a pipeline that renders 30-second clips: one key that submits and reads jobs, one tightly scoped key for operations, and a receiver that holds only the secret.

Verification has no key

verifyWebhook in @sume-com/sdk takes no client and makes no request. It checks the sume-v1 signature over <timestamp>.<raw_body> with your signing secret and the replay window (Verifying webhooks). The secret is not the API key.

So the process that receives deliveries should hold SUME_COM_WEBHOOK_SIGNING_SECRET and nothing else from Sume. If it is compromised, an attacker can forge deliveries to that one endpoint, but cannot spend your balance.

What each operation needs

Scopes are fixed when you create a key and you cannot add them later. A key that predates a scope does not have it, and the failure is 403 insufficient_scope. The only fix is a new key and a rotation to it (Authentication).

A sensible split

• Submit worker: a key that creates video jobs and reads their status and results. It never sees the signing secret.
• Receiver: no Sume key. Only the signing secret, as an environment variable that refuses to start when empty.
• Ops key: account:read, account:write, and jobs:write, kept off the servers and used from a trusted machine or a locked-down CI secret.
• Dashboard: rotation and Send test are also available there, so day-to-day you may not need the ops key in code at all.

Plan for the 24-hour rotation window

After a rotation, Sume signs every delivery with both the new and the previous secret for 24 hours, with the newest first in a comma-separated x-sume-webhook-signature. A receiver that accepts any matching sume-v1= entry survives the window. Upgrade the receiver before you rotate.

Redeliver sends the real terminal event again with a fresh timestamp and signature, even after Sume used all ten automatic attempts, and it does not use one of them. Use it after you fix your receiver, not as a polling substitute.

Checking a key before you rely on it

Responses show key metadata such as the id, name, prefix and scopes, but never the full secret, and GET /v1/me is the documented call to confirm a new key works. Run it right after you create the ops key, then try the one call it exists for, so you find a missing scope in setup and not during an incident.

Testing the layout

Try a redeliver with the receiver's own key on purpose. You should get a 403 insufficient_scope. If you get a success, that key has more power than the receiver needs, and it is worth narrowing before it leaks.