Authentication

Every endpoint under /api/v1 is authenticated with an API key sent as a bearer token.

Authorization: Bearer spk_3f8c1a...

The one exception is GET /presets, where the key is optional. Without a key you get the catalogue as seen by a free account; with one you get the catalogue as seen by your plan.

Key format

Keys issued today are the string spk_ followed by 48 hexadecimal characters.

spk_a7bd97d81dbc214fe801a6b917b834dc1f4e6a90c3b58d72

Two older prefixes, sk_ and vt_, are still accepted so that existing integrations keep working. New keys always use spk_.

A token that does not start with one of those three prefixes is not treated as an API key at all, and the request is rejected as unauthenticated.

Creating a key

Keys are created in the dashboard under API keys. Give each key a name that says where it runs, such as billing-service-prod, so that revoking one later is an obvious decision rather than a guess.

The full key is returned once, in the response to the creation request, and is never shown again. The dashboard afterwards displays only the name, the creation date and the last four characters. If you lose a key, revoke it and create another one.

Revoking a key

Revoking takes effect on the next request. A revoked key is rejected exactly like an unknown one, with 401 Unauthorized; the response deliberately does not distinguish the two cases.

Jobs already queued or processing under a revoked key continue to run. Revoking a key stops new requests, it does not cancel work.

Failure response

Any authentication problem returns the same body.

{
  "error": "Unauthorized",
  "message": "Valid API key required. Use format: Bearer spk_xxx or Bearer sk_xxx"
}

You get this for a missing Authorization header, a header that is not a bearer token, an unrecognised prefix, an unknown key, and a revoked key.

Ownership

A key belongs to one account and can only see that account's jobs. Reading a job that belongs to somebody else returns 404 Not Found rather than 403, so a key cannot be used to discover which job identifiers exist.

Keeping keys safe

• Keep keys in environment variables or a secret manager, never in a repository, a container image, or a client-side bundle.
• Call the API from your own backend. A key shipped to a browser or a mobile app is a key you have published.
• Use a separate key per environment and per service, so that a leak has a blast radius you can describe.
• Rotate by creating the new key, deploying it, and then revoking the old one. Both keys work during the overlap, so there is no window without a valid key.

Webhook signing is separate

The API key authenticates you to us. The webhook secret authenticates us to you, and it is a different value configured separately in the dashboard. See Webhooks.