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

# Authentication

> Get an API key, secure it, and use it on every request

CarrotHub API requests use an API key passed in the `Authorization` request header. Use an **Inference key** for model requests and an **Account key** for account APIs. See [API keys](https://www.carrothub.ai/docs/get-started/api-keys.md).

## Get an API key

**1. Open the API Keys tab**

Sign in to the [CarrotHub Console](https://www.carrothub.ai/app/api-keys)
and open the **API Keys** tab.

**2. Create an inference key**

Under **Inference keys**, click **Create key**. The console shows the full key string exactly once — copy it to a secret store immediately.

**3. Name the key**

Use a name that identifies its workload. You can disable or revoke the key from the same page.

> [!WARNING]
>
> The full API key is shown only once at creation. If you lose it, you
> cannot recover it — generate a new one and rotate.

## Send authenticated requests

Include the key as a Bearer token in the `Authorization` header:

```
Authorization: Bearer <API Key>
```

A minimal cURL request:

```bash highlight={3} theme={null}
curl https://api.carrothub.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CARROTHUB_API_KEY" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hi"}]}'
```

Use this inference key for LLM, image, video, speech, music, async task, and task-status requests. Account APIs require a separate Account key.

## SDK setup

Most OpenAI-compatible SDKs accept a `base_url` override. Point it at
CarrotHub and they "just work":

```python OpenAI Python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CARROTHUB_API_KEY"],
    base_url="https://api.carrothub.ai/v1",
)
```

```ts OpenAI Node theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CARROTHUB_API_KEY,
  baseURL: "https://api.carrothub.ai/v1",
});
```

## Best practices

* **Never commit keys to source control.** Use environment variables,
  `.env` files (gitignored), or a secret manager.
* **Rotate aggressively.** Generate a new key when a teammate leaves,
  when you suspect a leak, or on a fixed cadence.
* **One key per workload.** Per-service keys make leaks easy to scope and
  revoke without disrupting unrelated traffic.
* **Server-side only.** Treat the key like a database password — never
  ship it in a browser bundle or mobile app.

## Errors

| HTTP | Meaning | Likely cause |
| - | - | - |
| `401 Unauthorized` | Missing, malformed, or revoked key | Check the `Authorization` header is `Bearer <key>` |
| `402 Payment Required` | Insufficient balance | Top up in the [Console](https://www.carrothub.ai/app) |
| `429 Too Many Requests` | Rate limit / quota / daily-spend cap | Slow down or raise the limit |

The full code list lives in [Error codes](https://www.carrothub.ai/docs/get-started/error-codes.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.