Authentication

The Jobs API authenticates every request with a secret API key. Keys are prefixed with sk_ and are sent as a bearer token in the Authorization header.

Creating a key

Sign in, select your team, and open API Keys in the team's settings. Create a key, then copy it immediately — the full secret is shown only once at creation time. Store it somewhere safe (a secrets manager or environment variable). Creating and managing keys requires the Manage Settings permission on the team.

Making an authenticated request

Send the key as a bearer token on every request:

curl "https://www.puesto.dev/api/v1/jobs?limit=1" \
  -H "Authorization: Bearer sk_your_key_here"

Unauthorized responses

Requests with a missing or invalid key return 401 Unauthorized as an application/problem+json body:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid API key."
}

Entitlements

A few response fields are restricted: they are returned only to accounts we have explicitly entitled to them. The include=source parameter on Search jobs and Get a job by id is the one such field today — a key whose account lacks the source_identity entitlement gets 403 Forbidden rather than a response with the field missing. Entitlements are granted per account and are not part of any self-serve plan; contact us if you need one.

Key security

• Keep keys secret. Treat a key like a password — never commit it to source control or expose it in client-side code.
• Use the header, not the query string. Always send the key in the Authorization header so it is not captured in logs or browser history.
• Rotate on exposure. If a key may have leaked, revoke it from your team's API Keys settings and issue a new one.