API keys
Reference for /v1/api-keys. List, create, read, update, disable, rotate and revoke keys, set spend limits and expiry, and read per-key usage.
Last updated
On this page
Every endpoint on this page needs a key with full access or a dashboard session, and only ever sees keys of the caller's account: another account's key id answers 404 not_found. Guide: Authentication.
The key object
| Field | Type | Description |
|---|---|---|
id | string | key_… |
name | string | Your label, 1–80 characters. |
prefix | string | The first 12 characters of the secret, for example pa_live_Ab3x. |
lastFour | string or null | The secret's last 4 characters, so you can tell keys apart (pa_live_Ab3x…Qm2x). null for keys created before it was kept; rotating fills it in. Prefix and last four are the only parts ever shown again. |
kind | string | standard, or trial for an agent trial key. |
access | string | full, run or view. |
status | string | active, disabled, expired, paused or revoked. |
limitCredits | integer or null | Spend limit per window, in credits; null for none. |
limitInterval | string or null | daily, weekly, monthly, or null (a lifetime limit when limitCredits is set). |
spentInWindowCredits | integer | Credits spent in the current window. |
spentTotalCredits | integer | Credits spent since the key was created. |
windowResetsAt | string or null | When the current window ends (UTC). |
expiresAt | string or null | When the key expires; null for never. |
lastUsedAt | string or null | When the key was last used. |
createdAt | string | Creation time. |
createdBy | string or null | The user who created it, when created from the dashboard. |
Create and rotate responses add secret, the full key, returned that one time only.
GET /v1/api-keys
api.primaryapi.com/ v1/ api-keysAuth: API key with full access, or a dashboard session
All keys of the account, newest first, with revoked keys last. 200 OK: { "items": [<key>, …] }.
POST /v1/api-keys
api.primaryapi.com/ v1/ api-keysAuth: API key with full access, or a dashboard session
Creates a key. The body is strict: unknown fields are rejected.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | 1–80 characters. |
access | string | no | run (default), view or full. |
limitCredits | integer or null | no | Spend limit in whole credits, from 1 to 250,000,000. |
limitInterval | string or null | no | daily, weekly or monthly. Requires limitCredits. |
expiresIn | string | no | 1h, 1d, 7d, 30d, 90d, 180d, 1y or never (default). |
curl -sS -X POST "https://api.primaryapi.com/v1/api-keys" \
-H "Authorization: Bearer $PRIMARYAPI_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"support-bot","access":"run","limitCredits":6000,"limitInterval":"monthly","expiresIn":"90d"}'{
"id": "key_01JBXY0D2F4H6K8M0P2R4T6V8X",
"name": "support-bot",
"prefix": "pa_live_Q7mK",
"lastFour": "w2Zd",
"kind": "standard",
"access": "run",
"status": "active",
"limitCredits": 6000,
"limitInterval": "monthly",
"spentInWindowCredits": 0,
"spentTotalCredits": 0,
"windowResetsAt": "2026-11-01T00:00:00.000Z",
"expiresAt": "2027-01-28T14:05:09.120Z",
"lastUsedAt": null,
"createdAt": "2026-10-30T14:05:09.120Z",
"createdBy": null,
"secret": "pa_live_Q7mK…"
}Errors: 400 invalid_input (for example limitInterval without limitCredits, or a limit that is not a whole number of credits), 422 unprocessable when the account already has 100 active keys.
GET /v1/api-keys/{id}
api.primaryapi.com/ v1/ api-keys/ {id}Auth: API key with full access, or a dashboard session
One key. 200 OK: the key object.
PATCH /v1/api-keys/{id}
api.primaryapi.com/ v1/ api-keys/ {id}Auth: API key with full access, or a dashboard session
Changes a key. Send only the fields that change; the body is strict.
| Field | Type | Description |
|---|---|---|
name | string | New label, 1–80 characters. |
limitCredits | integer or null | New limit, in whole credits. null removes the limit and its interval. |
limitInterval | string or null | daily, weekly, monthly, or null for a lifetime limit. |
disabled | boolean | true disables the key (401 key_disabled); false enables it again. |
Changing only limitCredits keeps the current window and its spend. Changing the interval recomputes the window's spend from history. POST /v1/api-keys/{id} with the same body does the same, for clients that cannot send PATCH.
curl -sS -X PATCH "https://api.primaryapi.com/v1/api-keys/key_01JBXY0D2F4H6K8M0P2R4T6V8X" \
-H "Authorization: Bearer $PRIMARYAPI_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"disabled":true}'200 OK: the updated key. Errors: 404 not_found, 409 idempotency_conflict when the key is revoked (revoked keys cannot change).
DELETE /v1/api-keys/{id}
api.primaryapi.com/ v1/ api-keys/ {id}Auth: API key with full access, or a dashboard session
Revokes a key, permanently: its secret stops working at once. Revoking twice is harmless. 200 OK: the key, now with status revoked.
POST /v1/api-keys/{id}/rotate
api.primaryapi.com/ v1/ api-keys/ {id}/ rotateAuth: API key with full access, or a dashboard session
Issues a new secret for the same key: id, name, access, limits and history stay; the old secret stops working immediately. 200 OK: the key object with the new secret. Errors: 404 not_found, 409 idempotency_conflict for a revoked key.
GET /v1/api-keys/{id}/usage
api.primaryapi.com/ v1/ api-keys/ {id}/ usageAuth: API key with full access, or a dashboard session
Spending of one key, in credits. Query: days = 7, 30 (default) or 90.
| Field | Type | Description |
|---|---|---|
todayCredits, thisWeekCredits, thisMonthCredits | number | Calendar totals in UTC (weeks start on Monday). |
periodLabel | string | A human-readable label of the period. |
totalRequests | integer | Requests in the period. |
totalCredits | number | Credits spent in the period. |
successRate | number or null | Succeeded calls out of finished ones in the period (0–1); null when none finished. |
byApi | object[] | { sku, requests, credits } per API. |
daily | object[] | { date, requests, credits } per UTC day. |