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

# API Authentication

> Authenticate to the InsiteChat REST API using Bearer tokens. Create, list, and revoke API keys from the dashboard. Keys grant access to all chatbots you own.

The **InsiteChat API** uses **Bearer token authentication**. Every request must include a valid API key in the `Authorization` header. Keys are tied to your InsiteChat user account and grant access to all chatbots you own.

## Creating an API Key

<Steps>
  <Step title="Open the Developer page">
    From your dashboard, navigate to **Developer** → **API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Create API Key**, give it a descriptive name (e.g. *Production Server*, *Staging*, *Zapier Integration*), and click **Generate**.
  </Step>

  <Step title="Copy and store it">
    The full key is displayed **only once**. Copy it to a secure store immediately.
  </Step>
</Steps>

<Warning>
  You can have at most **5 active API keys** per account. If you hit the cap, revoke an unused key before creating a new one. If you lose a key, revoke it and create a fresh one — there is no way to retrieve a key after the creation screen closes.
</Warning>

## Key Format

API keys are URL-safe random tokens prefixed with `ic_`:

```
ic_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789AbCdEfGh
```

The first 8 characters (the `prefix`, which always starts with `ic_`) are shown in the dashboard so you can identify which key is which. The full key is never stored on InsiteChat servers — only its SHA-256 hash — which is why we can't show it back to you after creation.

## Using Your API Key

Include the API key in the `Authorization` header of every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://backend.insitechat.ai/api/v1/chatbots \
    -H "Authorization: Bearer ic_your-full-api-key-here"
  ```

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

  API_KEY = "ic_your-full-api-key-here"
  session = requests.Session()
  session.headers.update({"Authorization": f"Bearer {API_KEY}"})

  # Now every request via `session` is authenticated:
  chatbots = session.get("https://backend.insitechat.ai/api/v1/chatbots").json()
  ```

  ```javascript Node.js theme={null}
  const API_KEY = process.env.INSITECHAT_API_KEY;
  const headers = { Authorization: `Bearer ${API_KEY}` };

  const res = await fetch("https://backend.insitechat.ai/api/v1/chatbots", {
    headers,
  });
  const chatbots = await res.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://backend.insitechat.ai/api/v1/chatbots", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("INSITECHAT_API_KEY"))
  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

<Warning>
  Never expose your API key in browser JavaScript, mobile app bundles, public Git repos, or anywhere a customer could read it. Always call the API from a server you control.
</Warning>

## Listing Your Keys

`Dashboard` → **Developer** → **API Keys** shows every key on your account with:

* **Name** — the label you gave the key at creation
* **Prefix** — the first 8 characters (e.g. `ic_aBcDeF`) so you can spot which key is which
* **Last used** — the timestamp of the most recent successful API call (or *Never* if unused)
* **Created** — when the key was generated
* **Active / Revoked** — current state

## Revoking a Key

1. Find the key on the **API Keys** page.
2. Click **Revoke** and confirm.

Revoked keys stop working immediately. Any subsequent request using a revoked key returns `401 Unauthorized` (the same response as a malformed or unknown key — there is no separate error code distinguishing the two).

<Info>
  Use separate keys for each environment (production, staging, dev) and each integration (Zapier, your CRM sync, internal scripts). That way revoking a leaked key only impacts one consumer.
</Info>

## Rate Limiting

Each API key is rate-limited to **60 requests per minute** on a rolling 60-second window.

When you exceed the limit, the API returns:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"detail": "API rate limit exceeded. Max 60 requests per minute."}
```

There is **no `Retry-After` header** — back off on a fixed schedule (e.g. wait 60 seconds before retrying).

<Tip>
  Implement client-side throttling so you stay well under 60/min. If you genuinely need more headroom, [contact support](mailto:support@insitechat.ai).
</Tip>

## Error Responses

The API returns standard HTTP status codes. Error bodies follow the Django Ninja default shape — a single `detail` field describing what went wrong:

| Status | Typical `detail`                                         | Cause                                                            |
| ------ | -------------------------------------------------------- | ---------------------------------------------------------------- |
| `401`  | (Ninja default `Unauthorized`)                           | Missing, malformed, or revoked API key                           |
| `400`  | `Maximum 5 active API keys allowed.`                     | Hit the per-account key cap when calling the create-key endpoint |
| `404`  | `API key not found.`                                     | Tried to revoke a key that doesn't exist or isn't yours          |
| `429`  | `API rate limit exceeded. Max 60 requests per minute.`   | Per-key rate limit                                               |
| `429`  | `Monthly message limit reached.` (or similar quota text) | Plan message quota exhausted (only on the chat endpoint)         |

There is **no machine-readable `code` field** today — branch on the HTTP status (and on the `detail` text if you need to distinguish rate-limit `429`s from quota `429`s).