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."
}

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.