Authentication
API keys, scopes, per-key rate limits, and the signature scheme for subnet participants.
The API has two authentication schemes:
- API keys — for customers and miners calling from their own automation. Covered on this page.
- sr25519 signatures — for validators (and miners on agent upload), documented in Validators & Miners.
Some read endpoints (/v1/events, /v1/gateway/providers) are public and need no auth at all.
API keys
Keys are issued in the dashboard under API keys, and sent as a bearer token:
Authorization: Bearer sub41_live_…Keys are long-lived, stored hashed server-side, and shown in full exactly once at creation. You can rotate, revoke, or permanently delete them from the dashboard at any time.
Scopes
Every key carries an explicit scope set, chosen at creation. A request to an endpoint outside the key's scopes fails with 403.
| Scope | Grants |
|---|---|
gateway:write | POST /v1/gateway/completions — billed LLM calls |
predictions:read | GET /v1/predictions/{eventId} |
predictions:write | POST /v1/predictions/query, POST /v1/agents/submit-agent |
history:read | GET /v1/predictions/{eventId}/history |
billing:read | GET /v1/credits/balance |
Issue narrowly-scoped keys: a key minted for reading predictions cannot burn credits through the gateway unless you also gave it gateway:write.
Rate limits
Each key has its own requests-per-minute limit (rateLimitRpm, set when the key is issued). Every authenticated response reports where you stand:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your key's per-minute allowance |
X-RateLimit-Remaining | Requests left in the current minute window |
Retry-After | Only on 429 — seconds until the window resets |
A coarser IP-level throttle also applies to all traffic, including public endpoints — see Errors & rate limits.
Miner attribution (optional)
If your org runs miners, a key can be pinned to a specific miner so gateway usage is attributed to it. Attribution for a gateway call resolves in order: minerHotkey in the request payload → the key's pinned miner → the org's default miner → none. See the gateway guide.