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

# Authentication

> Bearer API keys — test and live — with scopes, IP allowlists, and spend caps.

Every request authenticates with an API key in the `Authorization` header:

```bash theme={null}
curl https://sandbox-api.platform.chipper.ai/v1/payouts \
  -H "Authorization: Bearer sk_test_..."
```

## Test and live keys

| Prefix      | Stack      | Behavior                                         |
| ----------- | ---------- | ------------------------------------------------ |
| `sk_test_…` | Sandbox    | Simulated rails, testnet chains. Free to hammer. |
| `sk_live_…` | Production | Real money. Guard accordingly.                   |

A key only works on its own stack — a `sk_test_` key against the production URL is just an invalid key. This makes it impossible to accidentally move real money with test code.

Keys are created in the dashboard under **Developers → API keys**. The full key is shown **once**, at creation. We store only a hash — if a key is lost, create a new one, switch your integration, and revoke the old (there is deliberately no "rotate" button; rotation *is* create → switch → revoke, so both keys work during the switchover).

## Scopes

Each key carries scopes — `payouts:write`, `recipients:read`, and so on — set at creation. A request with a key that lacks the needed scope fails with `403`:

```json theme={null}
{ "error": "forbidden", "message": "API key does not have the required scope" }
```

Give integration keys the narrowest scopes that do the job: a reporting service needs `payouts:read`, not `payouts:write`.

## IP allowlists

A key can be restricted to a list of caller IPs. Requests from any other address fail with `403` even with a valid key. Recommended for production keys running from fixed infrastructure.

## Spend caps

Live keys can carry daily / per-transaction / monthly USD caps, enforced across all currencies at current rates. A payout that would exceed a cap is rejected before any money moves.

Caps are how you hand a key to something you don't fully control — including an **AI agent**. Give an agent its own key with narrow scopes and a hard budget (say, $50 per transaction, $500 per day), and it can pay suppliers or settle invoices autonomously while the platform guarantees the blast radius: no bug, prompt injection, or runaway loop can spend past the cap.

## Failure modes

| Status | `error`                  | Meaning                                          |
| ------ | ------------------------ | ------------------------------------------------ |
| `401`  | `unauthorized`           | Missing, malformed, expired, or revoked key.     |
| `403`  | `forbidden`              | Valid key, but missing scope or blocked IP.      |
| `403`  | `organization_suspended` | The organization is suspended — contact support. |

Never ship an API key in client-side code, mobile apps, or repositories. Keys belong on your server.