# Authentication

Send your API key as a Bearer token or X-API-Key header. Access levels, spend limits and windows, expiry, rotation and paused keys.

Programs and agents authenticate with **API keys**. The dashboard uses a browser session instead (an httpOnly cookie); everything on this page is about keys.

## Sending your key

Send the key in the `Authorization` header as a Bearer token:

```bash
curl -sS "https://api.primaryapi.com/v1/requests?limit=5" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY"
```

If your HTTP client or proxy makes `Authorization` awkward, `X-API-Key` works the same way:

```bash
curl -sS "https://api.primaryapi.com/v1/requests?limit=5" \
  -H "X-API-Key: $PRIMARYAPI_API_KEY"
```

When both headers are present, `Authorization` wins. Keys are never accepted in the query string, so they do not end up in proxy and server logs.

A missing, mistyped, unknown or revoked key all answer `401 unauthorized` with the same message, on purpose: the response never reveals whether a key exists.

## Key format and storage

A key looks like `pa_live_` followed by 40 letters and digits. It is shown **once**, when you create or rotate it. We store only a SHA-256 hash, so nobody (including us) can show it to you again. The first 12 characters are kept as the key's `prefix`, which the dashboard and the API use to tell keys apart, for example `pa_live_Ab3x`.

## Access levels

Every key has one access level. Pick the lowest one that does the job.

| Access | Can | Cannot | Typical use |
|---|---|---|---|
| `run` (default) | Run and quote APIs, poll requests, re-read results, send feedback | Read the balance, usage or ledger, manage keys | Production services and agents |
| `view` | Read the balance, usage, ledger, credit orders, requests and results | Run or quote APIs (it can never spend), manage keys | Dashboards, monitoring, finance |
| `full` | Everything a key can do, including creating, changing, rotating and revoking keys | Buy credits by card (that needs the dashboard) | Admin scripts and automation |

Calling an endpoint above the key's level answers `403 forbidden`. The catalog endpoints (`GET /v1/apis`, `GET /v1/apis/{sku}`, `GET /v1/catalog`), the status endpoints and `POST /agent/signup` need no key at all. Every endpoint's required access is listed in the [API reference](/docs/api-reference).

Agent trial keys from [`POST /agent/signup`](/docs/agent-signup) have `run` access and their own trial budget.

## Spend limits

A key can carry its own spend limit in credits, on top of the workspace's balance. The limit is checked in the same transaction that holds the call's credits, so concurrent calls can never push a key past it.

| Field | Values | Meaning |
|---|---|---|
| `limitCredits` | a whole number of credits from 1 to 250,000,000, or `null` | Most the key may spend per window. `null` removes the limit. |
| `limitInterval` | `daily`, `weekly`, `monthly` or `null` | The window. `null` with a `limitCredits` means a lifetime limit. Requires `limitCredits`. |

Windows are calendar windows in UTC: a daily window resets at 00:00 UTC, a weekly window on Monday at 00:00 UTC, a monthly window on the 1st. A call is admitted only when the key's remaining allowance covers the **most** the call can cost (the same credits the balance holds for it); the unused part flows back to the allowance when the call settles. Over the limit, calls answer `402 key_limit_reached` and your balance is not touched. The key object shows `spentInWindowCredits` and `windowResetsAt` so you can see how close it is.

Create a key limited to 1,000 credits per day:

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/api-keys" \
  -H "Authorization: Bearer $PRIMARYAPI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-enrichment","access":"run","limitCredits":1000,"limitInterval":"daily"}'
```

Raise it later, or remove it with `"limitCredits": null`:

```bash
curl -sS -X PATCH "https://api.primaryapi.com/v1/api-keys/key_01JBXM3T5V7Q9R2K4N6P8W0Y1Z" \
  -H "Authorization: Bearer $PRIMARYAPI_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limitCredits":5000,"limitInterval":"weekly"}'
```

Changing only the amount keeps the current window and what was spent in it. Changing the interval recomputes the spend for the new window from your request history, so switching windows is never a way to reset a limit.

Managing keys over the API needs a key with `full` access (shown here as `PRIMARYAPI_ADMIN_KEY`); the dashboard does the same with your session. Request bodies are strict: a misspelled field such as `"limit"` is rejected rather than silently creating a key without a limit. An account can hold up to 100 active (not revoked) keys; creating one more answers `422 unprocessable`.

## Expiry

Set `expiresIn` when you create a key: `1h`, `1d`, `7d`, `30d`, `90d`, `180d`, `1y` or `never` (the default). After that moment every request with the key answers `401 key_expired`. Expiry cannot be extended; create a new key instead. Short-lived keys are a good fit for one-off jobs, contractors and demos.

## Disable, revoke, rotate

| Action | How | Effect |
|---|---|---|
| Disable | `PATCH /v1/api-keys/{id}` with `{"disabled": true}` | Requests answer `401 key_disabled`. Reversible with `{"disabled": false}`. |
| Revoke | `DELETE /v1/api-keys/{id}` | Permanent. The secret stops working at once; requests answer `401 unauthorized`. The key stays in your list with status `revoked`. |
| Rotate | `POST /v1/api-keys/{id}/rotate` | Returns a new secret for the same key: id, name, limits and usage history stay. The old secret stops working immediately. |

Rotation has no overlap window. For a zero-downtime switch, create a second key, deploy it everywhere, then revoke the first one.

## Paused keys

If your workspace has no credits left for more than 48 hours while calls keep being refused, its keys are **paused**: every request made with them answers `402 insufficient_balance` with a message saying so. Buy credits and they resume by themselves; nothing else needs to change. We email the account owner when the balance runs low, when it runs out, and when keys are paused.

## Key statuses

The `status` field of a key is one of `active`, `disabled`, `expired`, `paused` or `revoked`.

## Good practice

- Keep keys on the server. Never ship one in a browser bundle, a mobile app or a public repository.
- Use one key per service, environment and agent, each with a spend limit. A leaked key then has a known, small blast radius.
- Give dashboards and monitoring a `view` key: it can read everything it needs and can never spend.
- Read the key from an environment variable or a secrets manager, and redact `Authorization` and `X-API-Key` in your logs.
- If a key may have leaked, rotate or revoke it right away. We never ask for your key by email or chat.
