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.
Last updated
On this page
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:
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:
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.
Agent trial keys from POST /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:
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:
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
viewkey: it can read everything it needs and can never spend. - Read the key from an environment variable or a secrets manager, and redact
AuthorizationandX-API-Keyin your logs. - If a key may have leaked, rotate or revoke it right away. We never ask for your key by email or chat.