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

# Authentication

> Bearer tokens, scopes, and how requests are authorized.

All requests are authorized with a bearer token:

```
Authorization: Bearer <token>
```

Tokens are stored as SHA-256 hashes and compared in constant time. There are two
token families.

## Workspace keys (`sa_live_…`)

Grant access across the whole workspace. Authorization is governed by scopes on
the key:

| Scope     | Grants                                       |
| --------- | -------------------------------------------- |
| *(empty)* | Read access                                  |
| `read`    | Read access (list endpoints)                 |
| `write`   | Create affiliates and links                  |
| `track`   | `POST /v1/track/*` server-to-server tracking |
| `*`       | Everything                                   |

<Note>
  A key with no scopes can still **read**. Writes require `write` (or `*`);
  tracking requires `track` (or `*`).
</Note>

## Affiliate keys (`refa_live_…`)

Read-only tokens tied to a single affiliate. Every `/v1/affiliate/*` response is
filtered to that affiliate — a caller can only ever see their own clicks,
conversions, commissions, and links. Create and revoke these via the
`manage-affiliate-key` function (or the affiliate portal's Developer page).

## Errors

| Status | Body                                             | Meaning                         |
| ------ | ------------------------------------------------ | ------------------------------- |
| 401    | `{ "error": "unauthorized" }`                    | Missing / invalid token         |
| 403    | `{ "error": "insufficient_scope", "need": "…" }` | Token lacks the needed scope    |
| 400    | `{ "error": "…_required" }`                      | Missing required field          |
| 404    | `{ "error": "unknown_resource" }`                | Unknown path / not in workspace |