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

# Authentication

> Authenticate Admin API requests with a project API key sent in the x-magna-api-token header.

The Admin API authenticates every request with a **project API key**. Keys are
scoped to a single project and cannot be reused across projects.

## Get a key

Generate an API key from the Magna admin dashboard under your project's
**Settings → API keys**. Treat the key like a password — store it in a secrets
manager and never commit it or expose it in client-side code. If you don't see
the option, contact the Magna team to enable API access for your project.

## Send the key

Pass the key on every request in the `x-magna-api-token` header:

```sh theme={null}
curl -X POST https://app.magna.so/api/external/v1/allocations \
-H 'Content-Type: application/json' \
-H 'x-magna-api-token: YOUR_API_KEY' \
-d '{ "tokenId": "your_token_id" }'
```

## API key types

Magna offers two kinds of Admin API key, generated under **Settings → API keys**:

<CardGroup cols={2}>
  <Card title="Full Access API Token" icon="key">
    Scope `FULL`. Full read/write access to **every** Admin API endpoint — the
    default for backend integrations that manage allocations, funding, tokens,
    portals, and more.
  </Card>

  <Card title="Statistics API Key (Read-Only)" icon="chart-simple">
    Scope `EXTERNAL_STATS_READ`. Read-only access to the
    [Statistics](/apis/admin/statistics/total-supply) endpoints only (total,
    unlocked, and locked supply). Safe to share with third-party data providers.
  </Card>
</CardGroup>

| Key type                           | Scope                 | Can access                                                        |
| ---------------------------------- | --------------------- | ----------------------------------------------------------------- |
| **Full Access API Token**          | `FULL`                | All endpoints, including the Statistics endpoints.                |
| **Statistics API Key (Read-Only)** | `EXTERNAL_STATS_READ` | Only the Statistics endpoints (total / unlocked / locked supply). |

<Note>
  Most integrations use a **Full Access API Token**. Issue a **Statistics API
  Key** when an integration only needs to read supply figures — for example a
  public stats page or a market-data feed (CoinMarketCap, etc.) — so you can
  share it without granting full project access. A Full Access token also works
  on the Statistics endpoints.
</Note>

## Key lifecycle

* Keys are bound to a project — a key for project A cannot act on project B.
* Keys may have an **expiry**; expired keys are rejected.
* Last-used time is recorded each time a key authenticates.

## Errors

| Status | `error.type`        | When                                                                         |
| ------ | ------------------- | ---------------------------------------------------------------------------- |
| `401`  | `UnauthorizedError` | Missing or invalid token, or the key was not found.                          |
| `403`  | `ForbiddenError`    | Key belongs to a different project, is expired, or lacks the required scope. |

Errors use the standard envelope:

```json theme={null}
{
  "isProcessed": false,
  "error": {
    "type": "ForbiddenError",
    "message": "API key has expired"
  }
}
```