Authentication

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:

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:

Full Access API Token

Scope FULL. Full read/write access to every Admin API endpoint — the default for backend integrations that manage allocations, funding, tokens, portals, and more.

Statistics API Key (Read-Only)

Scope EXTERNAL_STATS_READ. Read-only access to the Statistics endpoints only (total, unlocked, and locked supply). Safe to share with third-party data providers.

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).

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.

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:

{
  "isProcessed": false,
  "error": {
    "type": "ForbiddenError",
    "message": "API key has expired"
  }
}

Overview

Admin API

Portal API

Webhooks

Get a key

Send the key

API key types

Full Access API Token

Statistics API Key (Read-Only)

Key lifecycle

Errors

​Get a key

​Send the key

​API key types

Full Access API Token

Statistics API Key (Read-Only)

​Key lifecycle

​Errors

Get a key

Send the key

API key types

Key lifecycle

Errors