Authentication

API key generation, authentication methods, and security.

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

Passing the key

Two methods are supported:

Header (recommended)

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

Query parameter

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

For WebSocket connections, use the query parameter:

wss://ws.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.

Generating a key

curl -s -X POST https://api.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”.

Key generation is rate limited to 1 per IP per day.

The raw API key is returned only once. It cannot be retrieved after creation — store it securely.

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.

Error responses

Status	Error	Fix
401	Missing or invalid API key	Include your key as x-api-key header or ?key= param
403	Invalid or inactive API key	Verify your key is correct, or generate a new one
429	Rate limit exceeded	Reduce request frequency. Default: 120 req/min