Source: https://www.puesto.dev/docs/authentication
Markdown source: https://www.puesto.dev/docs/authentication.md
Description: Authenticate requests with a secret API key sent as a bearer token.

# 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 [#creating-a-key]

Sign in, select your [team](/home), 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 [#making-an-authenticated-request]

Send the key as a bearer token on every request:

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

## Unauthorized responses [#unauthorized-responses]

Requests with a missing or invalid key return `401 Unauthorized` as an
[`application/problem+json`](/docs/errors) body:

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

## Key security [#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.