Authentication

API Key Authentication

All requests to /public/v1/ must include your API key in the request header:

X-API-Key: pub_live_YOUR_KEY_HERE

Key Format

pub_live_<48 hex characters>

Keys are hashed with SHA-256 and never stored in plain text. If a key is compromised, revoke it immediately from your dashboard. Only the key's short prefix (the first 8 characters after pub_live_) is retained for display.

Key Management

Key-management endpoints are authenticated with your dashboard JWT (Authorization: Bearer ...), not with an API key. API keys are scoped to your team — all keys on a team share the same plan, credits, and rate limit.

Create a Key

POST /public/keys

curl -X POST https://api.cardprices.io/public/keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production server"}'

Returns 201. The raw key is shown only once — copy it immediately.

{
  "key": "pub_live_a1b2c3d4e5f6...",
  "keyPrefix": "a1b2c3d4",
  "name": "Production server",
  "message": "Copy this key now — it will not be shown again."
}

A team may hold at most 20 active keys; exceeding that returns 400 KEY_LIMIT_REACHED.

List Keys

GET /public/keys

{
  "keys": [
    {
      "_id": "60f1a0b2c3d4e5f6a7b8c9d0",
      "keyPrefix": "a1b2c3d4",
      "name": "Production server",
      "isActive": true,
      "lastUsedAt": "2026-07-01T12:00:00.000Z",
      "createdAt": "2026-06-01T09:00:00.000Z",
      "createdBy": "60f1a0b2c3d4e5f6a7b8c9d1"
    }
  ]
}

Rename a Key

PUT /public/keys/:keyId

curl -X PUT https://api.cardprices.io/public/keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging server"}'

Returns the updated key: { "key": { ... } }.

Revoke a Key

DELETE /public/keys/:keyId

Soft-deletes the key (it stops working immediately) and returns { "ok": true }.

Rate Limits

Rate limits apply per team, per minute:

When rate-limited, the API returns 429 with a Retry-After header. See Rate Limits for header and response details.