Authentication

All API requests require authentication via a Bearer token. Your API key acts as the token.

API Key Format

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)

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"

import { AgentRef } from 'agentref'

const client = new AgentRef({ apiKey: 'ak_live_YOUR_KEY' })
const programs = await client.programs.list()

from agentref import AgentRef

client = AgentRef(api_key="ak_live_YOUR_KEY")
programs = client.programs.list()

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`	Review applications and block or unblock approved 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
`marketing_resources:read`	List, view, and download marketing resources
`marketing_resources:write`	Create social posts, manage media/status, create download URLs, and notify affiliates about marketing resources
`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, update, 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
`marketing_resources:read`	View, render, and download marketing resources for joined 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)

Overview

Programs

Affiliates

Applications

Affiliate Self-Serve

Conversions

Payouts

Fraud Flags

Coupons

Invites

Webhooks API

Billing

Merchant

Marketplace

Marketing Resources

API Key Format

Making Requests

Base URL

Scopes

Merchant Scopes

Affiliate Scopes

Scope Presets

Creating API Keys

Authentication Errors

​API Key Format

​Making Requests

​Base URL

​Scopes

​Merchant Scopes

​Affiliate Scopes

​Scope Presets

​Creating API Keys

​Authentication Errors

API Key Format

Making Requests

Base URL

Scopes

Merchant Scopes

Affiliate Scopes

Scope Presets

Creating API Keys

Authentication Errors