Account API
The AllenHark console runs on one HTTP API under /v1. It covers your account, your subscriptions and their access, checkout, billing and the managed bots. This page explains how it authenticates and how it behaves.
There is no API key for your account, and the account has no WebSocket API. To work with your account from an AI client or an agent, use the MCP server: its public tools are live now, and account tools, which sign in through your browser, come with the platform switch.
Two kinds of credential
| What you call | Credential |
|---|---|
| Your account: subscriptions, keys, checkout, billing, bots | A signed-in session (this page) |
| The data plane: RPC, gRPC, shreds, Relay | Your server's IP on the allowlist, or a product API key. See RPC, gRPC, ShredStream and Relay |
A product key (ahk_…) opens RPC, gRPC or shreds for one subscription. It never signs in to your account.
Sessions
You sign in with a magic link, a password, or Discord, GitHub or Google. Every sign-in ends in the same session:
- an access token that lasts 15 minutes, sent on each request as
Authorization: Bearer <token>; - a refresh token that lasts 30 days and is replaced each time it is used. Presenting a refresh token that was already used ends the whole session, since someone kept a copy.
The routes are under /v1/auth: login, refresh, logout, magic-link, profile, and oauth/{provider}/start and callback. GET /v1/me returns the signed-in account. Signing out or revoking a session takes effect on the next request, not when the access token expires.
A suspended account gets 403 on every request, whatever token it holds.
What the API covers
| Area | Routes |
|---|---|
| Account | /v1/me, /v1/auth/profile |
| Product keys and access | /v1/subscriptions/{id}/keys (list, create, rotate, revoke) and /v1/subscriptions/{id}/access-mode (ip, key or either) |
| Product settings | /v1/rpc, /v1/grpc, /v1/shredstream, /v1/jito-shreds, /v1/relay and /v1/vps: configuration, IP allowlists and connection splits |
| Checkout | /v1/checkout/quote, /v1/checkout/orders, /v1/checkout/orders/{id} and /v1/checkout/orders/{id}/activate |
| Billing | /v1/billing/balance, /v1/billing/ledger and the renew routes under /v1/billing/subscriptions |
| Managed bots | /v1/bots |
| Public, no sign-in | /v1/public/catalog, /v1/public/pricing, /v1/public/endpoints and /v1/public/prices/sol |
A product key is shown in full once, when it is created or rotated. After that the API lists it by its prefix (ahk_ and 8 characters), with its label, when it was created and when it was last used.
Writes
Writes take an Idempotency-Key header of up to 200 characters. Sending the same request again with the same key returns the first response and changes nothing, so a retry after a timeout is safe.
Another account's subscription, order or key answers 404, the same as one that doesn't exist.
Errors
Errors are JSON with a sentence and a code:
{ "error": "The name is at most 80 characters.", "code": "BAD_REQUEST" }| Status | Meaning |
|---|---|
| 400 | The request is malformed, a value is out of range, or a write has no Idempotency-Key |
| 401 | No session, or the access token has expired: refresh it and retry |
| 403 | The account is suspended, or the action needs a current session |
| 404 | Not found, or not yours |
| 409 | The change conflicts with the current state, for example revoking the last key while the access mode is key |
| 429 | Too many requests |
OpenAPI
The account, key and checkout routes are described in an OpenAPI document at /openapi/v1.json on the API host.