# 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.

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](/docs/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

`GET https://api.primaryapi.com/v1/api-keys`

Auth: 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

`POST https://api.primaryapi.com/v1/api-keys`

Auth: 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). |

```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":"support-bot","access":"run","limitCredits":6000,"limitInterval":"monthly","expiresIn":"90d"}'
```

```json title="201 Created"
{
  "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\}

`GET https://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\}

`PATCH https://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`.

```bash
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\}

`DELETE https://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

`POST https://api.primaryapi.com/v1/api-keys/{id}/rotate`

Auth: 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

`GET https://api.primaryapi.com/v1/api-keys/{id}/usage`

Auth: 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. |
