Authentication

The ZapAPI API uses bearer-token authentication. Every request must include an API key in the Authorization header:

Authorization: Bearer zap_live_your_key_here

Keys are scoped (per-project) and prefixed so you can tell at a glance what environment they belong to:

Creating an API keyCopy Anchor Link

Create keys from the dashboard (Settings → API Keys) or programmatically via the API Keys endpoints. Keys are shown once at creation time — store them immediately in a secrets manager.

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"]
  }'

The response contains the plaintext key exactly once:

{
  "data": {
    "id": "key_…",
    "name": "Production backend",
    "prefix": "zap_live_",
    "key": "zap_live_51H7…"   // ← shown ONCE, store immediately
  }
}

ScopesCopy Anchor Link

Scopes limit what a key can do. Always grant the minimum scopes your integration needs:

When a request is missing a scope, the API returns 403 Forbidden with a machine-readable code you can branch on.

Test modeCopy Anchor Link

Test keys behave identically to live keys, but nothing settles on mainnet:

• Invoice paymentRequests are valid BOLT-11 strings on a regtest/signet-style network.
• Webhook events carry livemode: false so your handler can distinguish them.
• The TypeScript SDK exposes zap.isTestMode as a convenience flag.

const zap = new ZapAPI('zap_test_…');
zap.isTestMode; // true

Use test mode for CI, local development and end-to-end tests — it is a fully functional sandbox, not a mock.

Rotating and revoking keysCopy Anchor Link

Rotate keys on a schedule (e.g., quarterly) and immediately on any suspicion of leakage:

1. Create a new key with the same scopes.
2. Deploy the new key to your service.
3. Revoke the old key from the dashboard or via DELETE /api-keys/:id.

Revoking is immediate — in-flight requests with the old key will return 401 Unauthorized.

Security best practicesCopy Anchor Link

• Store keys in a secrets manager (AWS Secrets Manager, Doppler, 1Password Connect, Vercel env vars). Never commit them to git.
• Restrict by IP (optional) from the dashboard for server-to-server integrations.
• Use one key per service so you can rotate and audit independently.
• Enable 2FA on the dashboard account that owns the keys.
• Audit key usage regularly — every authenticated request is logged with the key id and IP.

Other authentication surfacesCopy Anchor Link

The API also uses these for specific flows — you will not normally use them for server integrations:

• Dashboard JWT — short-lived session token for the web dashboard; used to call the API Keys, Team and Billing endpoints.
• LNURL-auth — passwordless sign-in for public pages (e.g., bio-link dashboards) using a Lightning wallet.
• NWC connection strings — delegated wallet access for NIP-47 clients.