Authentication

Authentication

All API endpoints (except /healthz, /readyz, and POST /v1/keys) require an API key.

Generating a Key

curl -s -X POST https://polynode.dev/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app"}'

Field	Type	Description
name	string (optional)	Label for the key. Defaults to “unnamed”.

Response:

{
  "api_key": "pn_live_a1b2c3d4e5f6...",
  "name": "my-app",
  "rate_limit_per_minute": 120,
  "message": "Store this key securely — it cannot be retrieved again."
}

Key generation is rate limited to 3 per IP per hour.

Passing the Key

Two methods are supported:

Header (recommended)

curl -H "x-api-key: pn_live_YOUR_KEY" https://polynode.dev/v1/markets

Query Parameter

curl https://polynode.dev/v1/markets?key=pn_live_YOUR_KEY

For WebSocket connections, use the query parameter:

wss://polynode.dev/ws?key=pn_live_YOUR_KEY

Key Format

API keys use the prefix pn_live_ followed by a random string. Legacy keys with qm_live_ prefix are also accepted.

Error Responses

401 — Missing or Invalid Key

{
  "error": "Missing or invalid API key. Use x-api-key header or ?key= param."
}

403 — Inactive Key

{
  "error": "Invalid or inactive API key."
}

429 — Rate Limited

{
  "error": "Rate limit exceeded. Retry after 1709136060."
}

Security

• API keys are SHA-256 hashed before storage. The raw key is never persisted.
• All traffic should use HTTPS in production.
• Rotate keys by generating a new one and decommissioning the old one.