Authentication
Authenticate every request using an API key.
API Key Types
SWAPS uses three API key types, determined by prefix:
| Prefix | Type | Use Case |
|---|---|---|
sk_live_ | Secret key | Server-side integration. Full access. Never embed in client-side code. |
pk_live_ | Publishable key | Public by design for widget/client-side use. Requires HMAC user authentication headers. |
swaps_ | Legacy key | Full access. Migration period — will be deprecated. |
Authentication Headers
Pass your API key via either header:
Authorization: Bearer <API_KEY>X-API-Key: <API_KEY>
Secret (sk_live_) and legacy (swaps_) keys are tenant-scoped credentials and must be treated like passwords. A publishable key (pk_live_) may be embedded client-side, but it does not authenticate a widget user by itself. Rate limits are enforced per tenant; respect x-ratelimit-* headers.
Server-Side Example (sk_live_)
curl -H "Authorization: Bearer sk_live_your_key_here" \
https://www.swapsapi.com/api/v2/partners/readiness
Widget / Client-Side (pk_live_ + HMAC)
Publishable keys (pk_live_) require HMAC user authentication. Include these additional headers:
X-Swaps-User-Id: <userId>
X-Swaps-User-Signature: <hmac_signature>
X-Swaps-User-Timestamp: <unix_timestamp>
The HMAC signature is computed as:
HMAC-SHA256(hmacSecret, "swaps-user:{userId}:{timestamp}")
Use the widget HMAC secret shown in the dashboard to generate this signature on your backend. Never send that secret to the browser. Signatures are valid for 24 hours.
V2 Widget Auth
For the embeddable widget (/api/v2 endpoints), use pk_live_ keys with HMAC headers. The widget sends the signed user headers generated by your backend. Some widget-capable endpoints are dual-use and also accept server keys from trusted server-side integrations; those server keys must still never be embedded in the widget or other browser code.