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

# Authentication

> Authenticate REST API requests with a Proceeds API key, scoped per endpoint.

The Proceeds REST API authenticates with **API keys** generated from your dashboard. Each key carries a set of scopes that determine which endpoints it can call.

## Key format

Keys use an `mpk_` prefix followed by 64 lowercase hex characters (32 random bytes):

```
mpk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
```

<Warning>
  The raw key is shown only once at creation and cannot be recovered later. Store it in a secret manager or environment variable — never in client-side code or version control.
</Warning>

## Send the key

Provide the key in either header. Both are equivalent:

<CodeGroup>
  ```bash Authorization theme={null}
  curl https://api.myproceeds.xyz/v1/me \
    -H "Authorization: Bearer mpk_your_key_here"
  ```

  ```bash X-Api-Key theme={null}
  curl https://api.myproceeds.xyz/v1/me \
    -H "X-Api-Key: mpk_your_key_here"
  ```
</CodeGroup>

## Scopes

Each key is granted a set of scopes. Write scopes imply the matching read scope.

| Scope               | Grants                                                    |
| ------------------- | --------------------------------------------------------- |
| `services:read`     | Read services                                             |
| `services:write`    | Create, update, delete services (implies `services:read`) |
| `paywalls:read`     | Read paywalls                                             |
| `paywalls:write`    | Create, update, delete paywalls (implies `paywalls:read`) |
| `transactions:read` | Read payment transactions                                 |
| `events:read`       | Read analytics events                                     |

A request to an endpoint your key isn't scoped for returns `403` with code `INSUFFICIENT_SCOPE` — see [Errors & rate limits](/api-reference/errors-and-rate-limits).

## Validate a key

Call `GET /v1/me` with any valid key to confirm it works and inspect the tenant and scopes it carries. No specific scope is required.

```bash theme={null}
curl https://api.myproceeds.xyz/v1/me \
  -H "X-Api-Key: mpk_your_key_here"
```

The response returns the associated user, the key's name and `keyPrefix`, and its scopes.

## Secret handling

Secret material is never returned by the API:

* Service `authConfig` values (upstream credentials)
* Paywall custom header values

These are always masked as `"***"` in responses. The field **names** are returned so you can see what's configured, but the plaintext values are not recoverable through the API.

<Card title="Errors & rate limits" icon="triangle-exclamation" href="/api-reference/errors-and-rate-limits">
  What an auth failure looks like, plus the per-key rate limit.
</Card>