Authentication

Every authenticated endpoint expects a Bearer JWT in the Authorization header. Keys are issued from the merchant dashboard, scoped to your account, and signed by RefCampaign.

Generate an API key

Open Settings → API keys in the merchant dashboard.
Click Create API key and give it a descriptive name (e.g. production-server, ci-backfill).
Copy the token. The dashboard shows it once — there is no recovery.
Store the token in a secret manager (Vercel, AWS Secrets Manager, GitHub Actions secrets…). Treat it like a password.

Use a key

Send the token on every API request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

curl example:

curl https://app.refcampaign.com/api/v1/campaigns \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY"

The token is opaque to your application. Do not parse it — its format may change between releases.

Token lifetime

API keys do not expire by default. They remain valid until you revoke them from the dashboard.

If you need rotating short-lived tokens (a common security control), rotate them yourself:

Generate a new key.
Roll the new value out to your servers.
Revoke the old key once the rollout is complete.

Revocation

In Settings → API keys, click Revoke next to the key. Active sessions on that key fail immediately with 401. Revocation is permanent — you cannot un-revoke.

A revoked key returns:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Public endpoints

A small number of endpoints accept anonymous traffic (rate-limited per IP):

POST /api/v1/track/click — click tracking from the browser SDK.
POST /api/v1/track/identify — session-to-customer binding.
POST /api/v1/affiliates/signup — public affiliate self-registration.
GET /api/v1/campaigns/{id}/public — public campaign profile for landing pages.

These endpoints do NOT require an Authorization header. They have stricter rate limits and reject malformed payloads with the same error envelope.

Security checklist

Never commit a key to git

Even in a private repo, leaked keys end up in CI logs, archived branches, and forks. Use environment variables and a secret manager — and rotate immediately if a key was ever committed.

Use a dedicated key per environment. Don't share the production key with staging or local dev.
Rotate after a suspected leak. Generate a new key, deploy it, revoke the old one.
Limit blast radius. If a service only needs to read commissions, eventually you'll be able to scope the key to that surface — for now, treat every key as full-account access.