API Keys

API keys are the primary way your backend talks to ZapAPI. They are bearer tokens sent in the Authorization header, scoped to a project, and prefixed by environment (zap_live_ / zap_test_).

Anatomy of a keyCopy Anchor Link

zap_live_51H7a9f3Kj2mNpQrStUvWxYz
└──┬──┘ └──┬─────────────────────────┘
   │       └─ 32+ random characters (secret)
   └───────── environment prefix: live | test

• The prefix tells you the environment at a glance.
• The secret is shown once at creation time and stored only as a bcrypt hash on our side — we can never recover it for you.
• Keys are scoped to a single project and can carry any subset of scopes (invoices:write, webhooks:read, …).

Creating a keyCopy Anchor Link

From the dashboard: Settings → API Keys → Create key. Programmatically:

curl -X POST https://api.zapapi.com/api/v1/api-keys \
  -H "Authorization: Bearer <dashboard-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "projectId": "proj_…",
    "scopes": ["invoices:write", "webhooks:write"],
    "expiresInDays": 90
  }'

Response (plaintext key shown once):

{
  "data": {
    "id": "key_…",
    "name": "Production backend",
    "prefix": "zap_live_",
    "key": "zap_live_51H7a9f3Kj2mNpQrStUvWxYz",
    "scopes": ["invoices:write", "webhooks:write"],
    "expiresAt": "2027-01-23T00:00:00.000Z",
    "createdAt": "2026-10-25T00:00:00.000Z"
  }
}

Listing and inspecting keysCopy Anchor Link

curl https://api.zapapi.com/api/v1/api-keys?projectId=proj_… \
  -H "Authorization: Bearer <dashboard-jwt>"

You can see the prefix, scopes, last used at, last used IP and expiration, but never the secret itself.

Rotating keysCopy Anchor Link

Rotate on a schedule (quarterly is a good default) and immediately on any suspicion of leakage:

Revoking a keyCopy Anchor Link

curl -X DELETE https://api.zapapi.com/api/v1/api-keys/key_… \
  -H "Authorization: Bearer <dashboard-jwt>"

Revocation is immediate and permanent. There is no "undo" — you must create a new key.

ExpirationCopy Anchor Link

Keys can be created with an optional expiresInDays. Expired keys return 401 Unauthorized with a key_expired code. Set a reminder a week before expiry so you have time to rotate.

Auditing usageCopy Anchor Link

Every authenticated request is logged with the key id, IP, user agent and endpoint. From the dashboard (Settings → API Keys → key → Activity) you can:

• See the last 30 days of usage per key.
• Spot keys that haven't been used in 90+ days (candidates for revocation).
• Detect unexpected IPs or user agents.

Common pitfallsCopy Anchor Link

• 401 after rotation — the old key is still in an env var somewhere. Grep your infra for the old prefix.
• 403 on a new key — the key is missing a scope. Re-create with the scope (scopes cannot be edited in place).
• Keys shared across services — makes rotation painful. Use one key per service so you can rotate independently.