Authentication

The Referral Engine API uses API keys to authenticate requests. You can view and manage your API keys in your dashboard.

API Key Types

Public Key (pk_live_xxx / pk_test_xxx)

• Safe to use in client-side code (browsers, mobile apps)
• Can create referral links and track basic events
• Cannot access sensitive data or admin operations
• Requests are rate-limited per IP address

Secret Key (sk_live_xxx / sk_test_xxx)

• Must be kept secret — never expose in client-side code
• Full access to all API endpoints
• Required for server-to-server integrations
• Higher rate limits

Making Authenticated Requests

Include your API key in the Authorization header:

curl https://api.referralengine.com/v1/links \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json"

Using the SDK

The SDK handles authentication automatically:

const referral = new ReferralEngine({
  apiKey: process.env.REFERRAL_ENGINE_SECRET_KEY
})

Test vs Live Keys

Each key type has test and live variants:

• pk_test_xxx / sk_test_xxx — Test mode, no real charges or events
• pk_live_xxx / sk_live_xxx — Live mode, real data

Use test keys during development. All test data is isolated and can be cleared at any time.

Rate Limiting

API requests are rate-limited to prevent abuse:

• Public Key: 100 requests per minute per IP
• Secret Key: 1,000 requests per minute per key

When rate limited, the API returns a 429 Too Many Requests response with aRetry-After header indicating when to retry.

Key Rotation

If you need to rotate your API keys (e.g., if a key is compromised):

1. Go to Settings → API Keys in your dashboard
2. Click Roll Key on the key you want to rotate
3. A new key is generated immediately
4. The old key remains valid for 24 hours to allow migration
5. Update your application with the new key