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

1. Open the Developer page

   From your dashboard, navigate to Developer → API Keys.

2. Create a key

   Click Create API Key, give it a descriptive name (e.g. Production Server, Staging, Zapier Integration), and click Generate.

3. Copy and store it

   The full key is displayed only once. Copy it to a secure store immediately.

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.

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:

cURL

curl https://backend.insitechat.ai/api/v1/chatbots \
  -H "Authorization: Bearer ic_your-full-api-key-here"

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.

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).

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.

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/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).

Implement client-side throttling so you stay well under 60/min. If you genuinely need more headroom, contact support.

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 429s from quota 429s).