Authentication

Phantom authenticates programmatic requests with a Bearer API key.

curl https://api.phantomrouter.ai/api/v1/me/vector-store \
  -H "Authorization: Bearer $PHANTOM_KEY"

Keys are stored hashed (SHA-256) - the plaintext is shown once, when the key is minted, and never again. Treat it like a password: keep it server-side, never ship it in a browser or mobile client.

A revoked key returns 401 UNAUTHORIZED ("API key has been revoked"). A terminated account returns 403 ACCOUNT_TERMINATED.

Scopes

Each endpoint requires a scope. A key only carries the scopes it was minted with.

Scope	Grants	Default on new keys
chat:companion	Chat, retarget, media-tag, vector-store config, chat preferences	Off - granted by us

Your credit balance, usage, and billing are viewed and managed in the dashboard, not through the API.

Requesting an endpoint without its scope returns:

{ "error": "FORBIDDEN", "message": "Missing required scope: chat:companion", "statusCode": 403 }

chat:companion is off by default

The Phantom chat surface is default-off so that a key can't reach it by accident. You can create and manage your own keys in the console, but chat:companion itself is granted per key by the Phantom team.

• Granted by us - to get a chat-enabled key, contact your account manager; we issue it with the chat:companion scope. A key you create yourself in the console at app.phantomrouter.ai won't carry the scope by default.
• Sessions - a logged-in app.phantomrouter.ai session always carries chat:companion, which is how the console itself talks to the API.

Sessions vs. keys

The console at app.phantomrouter.ai authenticates with a session cookie instead of a key; that's for the web app only. Programmatic clients should always use a Bearer API key.

CORS

Browser clients are subject to CORS. In production, the API only allows the app.phantomrouter.ai origin; the allowed headers are Content-Type and Authorization. Because keys must stay secret, you generally call Phantom from your backend, not directly from a browser.