All API requests require authentication via a Bearer token. Your API key acts as the token.
AgentRef uses prefixed API keys to distinguish key types:
| Prefix | Type | Description |
|---|
ak_live_ | Merchant | Full access to your programs, affiliates, conversions, payouts, and settings |
ak_aff_ | Affiliate | Access to affiliate self-serve endpoints (/me/*, marketplace) |
ak_onb_ | Onboarding | Limited scope for initial setup (create program, connect Stripe) |
Making Requests
Include your API key as a Bearer token in the Authorization header:
curl https://www.agentref.co/api/v1/programs \
-H "Authorization: Bearer ak_live_YOUR_KEY"
Base URL
All API endpoints are served from:
https://www.agentref.co/api/v1
Scopes
API keys are scoped to control access. When creating a key, you choose which scopes to grant.
Merchant Scopes
| Scope | Description |
|---|
merchant:read | Read merchant profile and settings |
merchant:manage | Update merchant profile and settings |
programs:read | List and view programs |
programs:write | Create and update programs |
affiliates:read | List and view affiliates |
affiliates:manage | Approve, block, and unblock affiliates |
conversions:read | List and view conversions |
payouts:read | List and view payouts |
payouts:write | Create payouts and mark as completed |
stats:read | View program, conversion, and payout statistics |
billing:read | View billing information and tiers |
billing:write | Subscribe and manage billing |
flags:read | List and view fraud flags |
flags:write | Resolve fraud flags |
webhooks:read | List and view webhook endpoints |
webhooks:write | Create, update, and delete webhook endpoints |
invites:claim | Claim invite tokens |
Affiliate Scopes
| Scope | Description |
|---|
profile:read | View own profile |
profile:write | Update own profile |
links:read | List own tracking links |
links:write | Create and delete tracking links |
earnings:read | View own commission earnings |
conversions:read | View own conversions |
payouts:read | View own payout history |
stats:read | View own statistics |
marketplace:read | Browse the program marketplace |
marketplace:apply | Apply to programs |
invites:claim | Claim invite tokens |
Scope Presets
For convenience, you can use presets when creating API keys:
| Preset | Includes |
|---|
merchant:full | All merchant scopes |
affiliate:full | All affiliate scopes |
readonly | All read-only scopes across both merchant and affiliate |
Creating API Keys
- Log in to your AgentRef dashboard
- Go to Settings → API Keys
- Click Create API Key
- Select scopes or a preset
- Copy the key – it won’t be shown again
Store your API key securely. Treat it like a password. Never commit API keys to version control or expose them in client-side code.
Authentication Errors
| Status | Code | Description |
|---|
401 | UNAUTHORIZED | Missing or invalid API key |
403 | INSUFFICIENT_SCOPE | API key doesn’t have the required scope for this action |
403 | FORBIDDEN | Action not allowed (e.g., accessing another merchant’s resources) |
