All API endpoints (except /healthz, /readyz, and POST /v1/keys) require an API key.
Passing the key
Two methods are supported:
For WebSocket connections, use the query parameter:
wss://ws.polynode.dev/ws?key=pn_live_YOUR_KEY
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”. |
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 |
