> ## Documentation Index
> Fetch the complete documentation index at: https://agentref.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the AgentRef API using API keys.

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:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.agentref.co/api/v1/programs \
    -H "Authorization: Bearer ak_live_YOUR_KEY"
  ```

  ```javascript Node.js theme={null}
  import { AgentRef } from 'agentref'

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

  ```python Python theme={null}
  from agentref import AgentRef

  client = AgentRef(api_key="ak_live_YOUR_KEY")
  programs = client.programs.list()
  ```
</CodeGroup>

## 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

1. Log in to your [AgentRef dashboard](https://www.agentref.co)
2. Go to **Settings → API Keys**
3. Click **Create API Key**
4. Select scopes or a preset
5. Copy the key – it won't be shown again

<Warning>
  Store your API key securely. Treat it like a password. Never commit API keys to version control or expose them in client-side code.
</Warning>

## 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) |