Authentication

Every authenticated endpoint expects a Bearer token in the Authorization header. Keys are issued from the merchant dashboard, scoped to your account, and prefixed rc_live_ (production) or rc_test_ (test mode).

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 rc_live_...

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"
  }
}

Browser SDK endpoints

The /api/v1/* merchant API currently requires a Bearer token. Browser SDK tracking uses public, rate-limited endpoints outside the v1 merchant API surface:

• POST /api/track/click — click tracking from the browser SDK.
• POST /api/track/identify — session-to-customer binding.

These endpoints do NOT require an Authorization header. They are not included in the v1 OpenAPI playground because they are SDK/browser integration endpoints, not merchant API-key endpoints.

Security checklist

• 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.