Docs › Authentication

Authentication

Swaypi uses Bearer-token authentication. One key per integration; the key carries the tier (free, builder, studio, platform) which controls rate limits, batch sizes, and field-level permissions.

How to authenticate

Pass your API key in the Authorization header on every request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.swaypi.com/v1/me

import requests

r = requests.get(
    "https://api.swaypi.com/v1/me",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=10,
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://api.swaypi.com/v1/me", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
if (!r.ok) throw new Error(`Swaypi ${r.status}`);
console.log(await r.json());

Successful response

{
  "tier": "builder",
  "requests_remaining": -1,
  "rate_limit_per_minute": 600
}

requests_remaining returns -1 when the daily ceiling is unmetered for your tier (paid tiers).

Tiers

See the pricing page for current rates per tier.

Rate-limit headers

Every authenticated response includes three headers describing your current budget:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1718480820

X-RateLimit-Reset is a UNIX timestamp at which the per-minute counter resets. When you hit 0, subsequent requests return 429 Too Many Requests until the reset.

Key rotation

Rotate keys at any time from the dashboard. The old key remains valid for 24 hours after rotation to give you time to deploy the new one without downtime. After 24 hours, the old key returns 401 Unauthorized and the new key is the only valid credential.

If a key is compromised, revoke it immediately. Revoked keys stop working in under 30 seconds and cannot be restored — generate a new one.

Per-tier field permissions

Some response fields are tier-gated. If your tier doesn't include a field, the field is omitted from the response (not nulled, not returned with a placeholder). The most common gated field is contact_email, which requires the Builder tier or higher.

If your application requires gated fields, the response X-Swaypi-Tier-Gated header lists any fields that were omitted due to tier:

X-Swaypi-Tier-Gated: contact_email,audience_geo.detail

Common errors

401 Unauthorized. Missing or invalid Authorization header. Verify you're including Bearer and that the key hasn't been rotated.

403 Forbidden. Your key is valid but your tier doesn't include the endpoint or field you requested. The response detail field names the required tier.

429 Too Many Requests. Rate limit hit. Wait until X-RateLimit-Reset and retry. Implement exponential backoff in production clients.

Security best practices

Keep keys server-side. Never embed a Swaypi key in client-side JavaScript, mobile app bundles, or public source control. Use environment variables and a server-side proxy if you need to surface Swaypi data in a browser.

Rotate keys quarterly as a baseline. Rotate immediately if you suspect exposure, after personnel changes on integration teams, or after any incident that touched the storage location.