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

1. Open Settings → API keys in the merchant dashboard.
2. Click Create API key and give it a descriptive name (e.g. production-server, ci-backfill).
3. Copy the token. The dashboard shows it once — there is no recovery.
4. 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:

1. Generate a new key.
2. Roll the new value out to your servers.
3. 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. Use environment variables and secret managers.
• 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.