- API
- Authentication
Guide
Authentication
and security.
One access class for the public API: a Bearer token, issued to paid and trial accounts. This page is what a token can do, how it is checked, and what the refusals mean.
The token
- Applies to every endpoint under
/api/mcp/data/*, the programmatic surface these docs describe. - Send
Authorization: Bearer avmcp_<token>. Tokens are SHA-256-hashed server-side and checked for active status and expiry on every call; usage is recorded per call and shown under Account, then API Access. - The Account, then API Access tab creates and revokes your own tokens: up to 3 active, each secret shown once, one-year expiry by default. It is available on every paid or trial plan. What a token can reach follows the plan: each endpoint enforces the same feature tier as its web twin, and utility endpoints (search, expirations, stock, calendars) work on any paid plan.
- Pasting your token into a local MCP config, a private setup chat, or the console on an endpoint page is the intended, safe way to use it. Rotate a token only if it is exposed somewhere public: a committed file, a shared screenshot, a public post. Rotation is one click on the same page.
- Always call
https://apexvol.com, neverwww.: the www host answers with a redirect and most HTTP clients drop the Authorization header when they follow it, so the retried call fails with 401.
What a refusal means
| Status | Body | Meaning |
|---|---|---|
401 | {"error": "…"} | Missing or malformed header (the value must start with avmcp_), or a revoked or expired token. |
403 | {"error": "…", "tier_required": "basic"} | The owning account has no active paid or trial subscription. |
403 | {"error": "…", "upgrade_required": true, "required_tier": "premium", "your_tier": "basic"} | This endpoint sits above the account's plan. Each endpoint page states its tier. |
403 | {"error": "…", "beta_required": true} | API access is not enabled on the owning account. |
426 | {"error": "…", "upgrade_required": true} | The apexvol-mcp client is below the minimum version. Reinstall or update it. |
Repeated authentication failures from one address are throttled (20 in 15 minutes); a valid token never trips it. The full status list is on the errors page.
The hosted MCP connector
Adding https://apexvol.com/mcp-server as a connector in Claude, Cursor or ChatGPT uses OAuth instead of a pasted token: you sign in, approve read-only access, and a token labelled Claude connector appears on your account. Revoke it there to disconnect. The same tier rules apply.
Security notes
- Always HTTPS. Tokens travel in headers, never in the URL, and the try-it console on the endpoint pages keeps a pasted token in the tab's session storage only.
- Maintenance mode: when enabled, every API request returns 503
{"error": "maintenance"}. - Tickers are validated against a strict pattern; out-of-range numeric parameters are clamped to their documented bounds rather than rejected, unless an endpoint page says otherwise.
- The web app's own session-cookie API is not part of the public surface and is not documented here.
Included with
every paid plan.
From $55 a month, tier-matched: your token queries the data your plan includes and Pro unlocks the full surface.
Real market data, not a sandbox. See it live on AAPL.