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

# API Keys

> How to authenticate with the Earn API using API keys.

## API Keys

All Earn API endpoints require an API key. Pass it via the `X-API-Key` header on every request.

Use the API key that was requested when you created your organization (or contact the Turtle team if you need one). Once you have it, copy it and store it securely.

There are two types of API keys:

* **Publishable Key (`pk_live_`)** — Use in browser/client-side applications.
* **Secret Key (`sk_live_`)** — Use from your backend only. Never expose in client-side code.

### Publishable Key

<CodeGroup>
  ```bash curl theme={null}
  curl https://earn.turtle.xyz/v1/opportunities \
    -H "X-API-Key: pk_live_xxxxx"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch('https://earn.turtle.xyz/v1/opportunities', {
    headers: { 'X-API-Key': 'pk_live_xxxxx' }
  })
  ```
</CodeGroup>

### Secret Key (for server-side integrations)

Use this from your backend. Never expose it in client-side code.

<CodeGroup>
  ```bash curl theme={null}
  curl https://earn.turtle.xyz/v1/opportunities \
    -H "X-API-Key: sk_live_xxxxx"
  ```

  ```typescript Node.js theme={null}
  const res = await fetch('https://earn.turtle.xyz/v1/opportunities', {
    headers: { 'X-API-Key': process.env.TURTLE_SECRET_KEY! }
  })
  ```
</CodeGroup>

## Rate Limits

Rate limit information is returned in response headers:

| Header                  | Description                           |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Hourly cost unit budget               |
| `X-RateLimit-Remaining` | Cost units remaining this hour        |
| `X-RateLimit-Used`      | Cost units consumed this hour         |
| `X-Monthly-Limit`       | Monthly cost unit cap (if configured) |
| `X-Monthly-Usage`       | Cost units consumed this month        |
| `X-Monthly-Remaining`   | Cost units remaining this month       |

When a limit is exceeded, the API returns `429 Too Many Requests`.