Authentication

The header forms Tickwire accepts, token kinds, and how to narrow a token's reach.

Every request carries a key or token. We accept each of the forms the APIs we’re compatible with use, so existing clients work unchanged:

Prefer headers. Query parameters end up in logs more easily; we redact them from ours.

WebSockets: header or query parameter

The WebSocket and socket.io upgrade accepts the same headers as REST: auth-token, X-API-Key or Authorization: Bearer. A key in a header stays out of URLs, so any proxy or tool between you and us never logs it. Use a header whenever your client can set one:

import websockets

async with websockets.connect(
    "wss://api.tickwire.io/users/current/accounts/acc_7Qx/ws",
    additional_headers={"auth-token": TW_KEY},
) as ws:
    ...

// Node.js (the ws package)
const ws = new WebSocket("wss://api.tickwire.io/users/current/accounts/acc_7Qx/ws", {
  headers: { "auth-token": process.env.TW_KEY },
});

Browsers can’t set headers on a WebSocket, so in a browser the query parameter is the only way, and it stays supported. There, use a scoped token with a short time-to-live and only the accounts the page needs, never a full API key. We replace the value of auth-token, api_key and similar parameters with REDACTED in every log we write, our servers’ access logs included.

Token kinds

Tickwire separates developer credentials based on whether orders are placed directly by code or guided by an AI assistant:

1. API keys (tw_live_ and tw_ro_)

Created under API keys in the dashboard.

• Full keys (tw_live_): For custom scripts, bot integrations, prop firm workflows, and direct trading. Can trade, manage accounts, and read.
• Read-only keys (tw_ro_): Can query balances, quotes, positions, and history, but cannot trade or change settings.
• Headers to send: Authorization: Bearer <key> or X-API-Key: <key>.
• Target routes: /users/current/… and /v1/….

2. Agent keys (twag_)

Created under AI agents > Keys in the dashboard.

• Built specifically for AI assistants (Google Antigravity, Claude, ChatGPT, Cursor, Windsurf).
• Guarded execution: Each key is linked to an instant kill switch and evaluated by your pre-trade decision hook before orders reach the broker.
• Headers to send: In MCP clients, send Authorization: Bearer <key>. For direct HTTP calls, send X-Tickwire-Agent-Key: <key>.
• Target routes: /v1/agent/… routes and the MCP server. Direct terminal routes reject agent keys with 401 invalid_token to protect you from ungated agent orders.

3. Scoped tokens

Narrowed from an API key for browser pages or frontends: limited to certain accounts, with a time-to-live and optional IP allowlist. A token with an allowlist is checked against your real public address on every request and WebSocket, whatever X-Forwarded-For says. From anywhere else it gets 403 ip_not_allowed; the answer never shows the allowlist.

Every key and token value is shown once, in the answer that creates it (or rotates a read-only key). We keep only a SHA-256 digest of each key (full tw_live_, read-only tw_ro_ and sandbox twsk_ keys, like API tokens and agent keys), so nobody can show it again, us included. Lists and reads show only a short preview such as tw_live_ab12…, and asking the dashboard to reveal a key answers 400 not_revealable. Store the value when you create it; if you lose it, rotate or revoke the key and create a new one.

Keys issued before 2026-10-03 start with fxs_ and keep working.

Testing your key: Mac, Linux & Windows

Testing an API key (tw_live_ or tw_ro_)

macOS / Linux (Terminal):

curl -s -H "Authorization: Bearer <YOUR_API_KEY>" \
  https://api.tickwire.io/users/current/accounts

Windows (PowerShell):

curl.exe -s -H "Authorization: Bearer <YOUR_API_KEY>" `
  https://api.tickwire.io/users/current/accounts

Testing an Agent key (twag_)

macOS / Linux (Terminal):

curl -s -H "X-Tickwire-Agent-Key: <YOUR_AGENT_KEY>" \
  https://api.tickwire.io/v1/agent/accounts

Windows (PowerShell):

curl.exe -s -H "X-Tickwire-Agent-Key: <YOUR_AGENT_KEY>" `
  https://api.tickwire.io/v1/agent/accounts

Rotation doesn’t restart anything

Creating, rotating or revoking a key never restarts a terminal or drops a broker connection.

Mistakes and what you’ll see

On the /users/current/… routes, error holds the class name (UnauthorizedError for 401, ForbiddenError for 403) and the code above is in code.