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

# Authentication

> API key and pay-per-request authentication

Shoal supports two access modes:

* API key for regular usage and broader account access
* pay-per-request for the public paid surface

## Option 1: API Key (Bearer Token)

Send your API key in the `Authorization` header using the Bearer scheme.

```
Authorization: Bearer <YOUR_API_KEY>
```

Get your API key at [app.shoal.xyz](https://app.shoal.xyz).

### Error Responses

| Status | Body                                                       | Cause                     |
| ------ | ---------------------------------------------------------- | ------------------------- |
| 401    | `{ "error": "Authorization header missing or malformed" }` | No header or bad format   |
| 401    | `{ "error": "API key missing" }`                           | Empty key after `Bearer ` |
| 401    | `{ "error": "Invalid API key" }`                           | Key not found             |

## Option 2: Pay-Per-Request

No API key is required for the public paid endpoints. Shoal supports pay-per-request flows over HTTP 402.

Most users do not need protocol details to get started. If you are building a custom client or agent, see the dedicated [MPP/x402 guide](/integrations/mpp).

### How It Works

1. Send a request to a paid endpoint without an API key
2. Shoal returns `402 Payment Required`
3. Your client pays and retries
4. Shoal returns the response

### Quick Start

Use the `mppx` CLI to test a paid endpoint:

```bash theme={null}
npx mppx account create
npx mppx pay GET https://api.shoal.xyz/v1/signal/top
```