Authentication & API keys

Secret API keys, test vs live mode, scopes, rotation, expiry and IP allowlists.

Every request is authenticated with a secret API key sent as a Bearer token:

GET /api/v1/account HTTP/1.1
Authorization: Bearer sk_test_51Hx…

curl https://swaglists.com/api/v1/account \
  -H "Authorization: Bearer $API_KEY"

const res = await fetch("https://swaglists.com/api/v1/account", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});

res = requests.get("https://swaglists.com/api/v1/account", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"})

HTTP Basic authentication with the key as the username and an empty password also works (curl -u "$API_KEY:"), for tools that only support Basic auth.

#Test and live keys

Both modes use the same base URL — the key decides the mode. Products, designs and files are shared between modes, so a product you created in test mode can be ordered live without changes. Everything else (orders, webhook endpoints, events, wallet) is separate: a live key cannot see test orders and vice versa.

Creating a live key requires a verified email address (see the going live checklist). Live keys work while live mode is enabled for your account; if it is not (for example while support reviews a new account), they return 403 live_mode_disabled.

#Creating keys

Create keys in the dashboard under Developers → API keys (owners, admins and developers can). For each key you choose:

• Mode — test or live.
• Access — full access, read-only, orders only, or individual scopes.
• Expiry (optional) — the key stops working at that date (at most 5 years ahead).
• IP allowlist (optional) — the key only works from these addresses.

The full secret is shown once, when the key is created. We store only a hash; if you lose a key, roll it or create a new one. The dashboard shows a key's prefix and last four characters so you can recognize it, and the Logs page shows every request made with it.

#Scopes

Give each integration only what it needs. A :write scope includes the matching :read scope; * is full access.

A request outside the key's scopes fails with 403 insufficient_scope; the error's required_scope tells you which scope is missing.

#Rotating keys

Roll a key (Developers → API keys → Roll) to replace its secret, for example when a team member leaves or a secret may have leaked. You choose when the old secret stops working: now, in 1 hour, 24 hours or 7 days. During the overlap both secrets work, so you can deploy the new secret without downtime:

1. Roll the key with an overlap (e.g. 24 hours) and copy the new secret.
2. Deploy the new secret to your servers.
3. Check Developers → Logs to confirm no requests use the old key anymore.

Revoke a key to stop it immediately. Rolled, revoked and expired keys return 401 invalid_api_key with a message saying why.

#IP allowlists

An allowlist accepts up to 50 IPv4/IPv6 addresses or CIDR ranges (for example 203.0.113.7 or 10.0.0.0/8). Requests from other addresses fail with 403 ip_not_allowed.

#Errors