> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polynode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Tabs>
  <Tab title="Header (recommended)">
    ```bash theme={null}
    curl -H "x-api-key: pn_live_YOUR_KEY" https://api.polynode.dev/v1/markets
    ```
  </Tab>

  <Tab title="Query parameter">
    ```bash theme={null}
    curl "https://api.polynode.dev/v1/markets?key=pn_live_YOUR_KEY"
    ```
  </Tab>
</Tabs>

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.

## Account-level usage

All active API keys owned by the same account contribute to one shared monthly usage total. Creating, renaming, rotating, or using multiple keys does not create separate allowances or reset usage.

The [usage dashboard](https://polynode.dev/dashboard/usage) is authenticated by your signed-in account; you do not submit a raw API key to view it. See [Monthly usage allowances](/guides/rate-limits#monthly-usage-allowances) for the exact meters and included plan capacity.

## Generating a key

```bash theme={null}
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**.

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

## 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. Free tier: 60 req/min         |