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

# Authentication

> Request an API key, send it on every request, and stay within the rate limit.

Every endpoint except [`GET /health`](/api/dex-aggregator/endpoints/health) requires an API key.

## How to get an API key

API keys are currently issued directly by the o1 team. Self-serve key creation is on the roadmap; for now, the flow is:

<Steps>
  <Step title="Reach out">
    Contact the o1 team through your usual partnership or support channel and request a DEX Aggregator API key. Include a short description of your integration (app name, expected volume, environment) so we can size your rate limit correctly.
  </Step>

  <Step title="Receive your key">
    The team provisions a key scoped to your integration and shares it securely. Each key is independent, so you can request additional keys for staging, dev, or per-environment isolation.
  </Step>

  <Step title="Store it securely">
    Treat your API key like a password. Keep it server-side, never commit it to source control, and never expose it in browser-side code.
  </Step>
</Steps>

<Tip>
  Need to rotate or revoke a key? Reach out to the same channel. The team can create a replacement and revoke the old one with a short overlap window so you can deploy without downtime.
</Tip>

## Sending the key

Pass your key on every request via the `x-api-key` HTTP header.

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X POST https://quiet-bloodhound-531.convex.site/quote \
    -H "x-api-key: o1_your_key_here" \
    -H "content-type: application/json" \
    -d '{
      "chainId": 8453,
      "tokenIn": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenOut": "0x4200000000000000000000000000000000000006",
      "amountIn": "1000000000",
      "slippageBps": 100
    }'
  ```

  ```ts TypeScript theme={null} theme={null}
  await fetch(`${API_URL}/quote`, {
    method: "POST",
    headers: {
      "x-api-key": process.env.O1_API_KEY!,
      "content-type": "application/json",
    },
    body: JSON.stringify({ /* ... */ }),
  });
  ```

  ```python Python theme={null} theme={null}
  import os, requests

  requests.post(
      f"{API_URL}/quote",
      headers={
          "x-api-key": os.environ["O1_API_KEY"],
          "content-type": "application/json",
      },
      json={ ... },
  )
  ```
</CodeGroup>

<Warning>
  Never expose your API key in client-side JavaScript. Proxy through your own server. If your key has leaked, revoke it immediately and rotate.
</Warning>

## Rate limits

The default rate limit is **120 requests per minute per API key**. Higher tiers are available on request — contact the o1 team if you expect sustained traffic above that.

The window is sliding (60 seconds), enforced server-side. When you exceed it you get a `429`:

```json theme={null} theme={null}
{
  "error": "rate limit exceeded",
  "limit": 120,
  "windowSec": 60
}
```

See [Rate limits](/api/dex-aggregator/reference/rate-limits) for the recommended retry strategy.

## Error responses

<Tabs>
  <Tab title="401 Unauthorized">
    Missing or invalid `x-api-key`.

    ```json theme={null} theme={null}
    { "error": "unauthorized" }
    ```
  </Tab>

  <Tab title="429 Rate limited">
    You've exceeded the per-minute quota. Back off for at least one second before retrying.

    ```json theme={null} theme={null}
    {
      "error": "rate limit exceeded",
      "limit": 120,
      "windowSec": 60
    }
    ```
  </Tab>
</Tabs>

## Best practices

<CardGroup cols={2}>
  <Card title="One key per integration" icon="layer-group">
    Use a distinct key per app, environment, or backend service. Makes revocation painless when something rotates.
  </Card>

  <Card title="Rotate proactively" icon="rotate">
    Rotate keys quarterly or whenever an engineer with access leaves the team. Old keys can stay live for a short overlap window during the migration.
  </Card>

  <Card title="Log key usage server-side" icon="chart-bar">
    Tag your outbound requests with a request ID so you can correlate API errors with your server logs.
  </Card>

  <Card title="Honor 429s gracefully" icon="hand">
    On `429`, back off and retry with jitter. Don't hammer.
  </Card>
</CardGroup>