Authentication - Chataigne Docs

The Chataigne API authenticates every request with an API key passed in the x-api-key header. There are two separate API surfaces, each with its own key type. Keys are never interchangeable across surfaces.

Surface	Base path	Key type	Key prefix
Chataigne API (public)	`/v1`	Location / organization key	`ch_org_`
Admin API	`/admin/v1`	Admin key	`ch_admin_`

All requests go to the same host:

https://server.chataigne.ai

API keys are secret credentials that act on behalf of your account. Treat them like passwords: never commit them to source control, never log them, and never embed them in browsers, mobile apps, or any client-side code. See Keeping keys safe.

Authenticating a request

Send your key in the x-api-key header on every request. There is no Authorization: Bearer scheme — only x-api-key is accepted.

curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: ch_org_..."

Dashboard sessions are not API credentials. A logged-in dashboard session cannot be used to call /v1 or /admin/v1 — these surfaces only accept x-api-key.

The two surfaces

Chataigne exposes two independent API surfaces. Each is versioned by path (/v1, /admin/v1) and accepts exactly one key type.

Chataigne API

Path /v1. Read and manage a single organization and its locations, settings, and special closings. Authenticated with location / organization keys (ch_org_).

Admin API

Path /admin/v1. Provision and manage organizations and locations across accounts. Authenticated with admin keys (ch_admin_).

Public API — `/v1`

The public Chataigne API is scoped to the organization (and its locations) that the key belongs to. Use a ch_org_ key.

curl https://server.chataigne.ai/v1/organizations \
  -H "x-api-key: ch_org_..."

Admin API — `/admin/v1`

The Admin API performs account-level operations such as creating organizations and locations. Use a ch_admin_ key.

curl https://server.chataigne.ai/admin/v1/organizations \
  -H "x-api-key: ch_admin_..."

Strict surface separation

Keys are bound to their surface. Sending a key to the wrong surface is rejected — it is never silently downgraded or upgraded. This containment is enforced on every request.

Scenario	HTTP status	Error type
Valid key, correct surface	`200`	—
Missing or malformed key	`401`	`authentication_error`
Wrong key type for the surface	`403`	`authorization_error`

An admin key sent to /v1, or an organization key sent to /admin/v1, returns 403 authorization_error — not 401. A 401 means the key is absent or unrecognized; a 403 means the key is valid but not allowed on this surface. Use this distinction when debugging: 403 is almost always a surface/key-type mismatch.

Missing key → 401

curl https://server.chataigne.ai/v1/locations

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided. Pass your key in the x-api-key header.",
    "request_id": "req_8f2c1a9d4e7b"
  }
}

Wrong key type → 403

Sending an admin key to the public surface:

curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: ch_admin_..."

{
  "error": {
    "type": "authorization_error",
    "code": "wrong_key_surface",
    "message": "An admin key cannot be used on /v1. Use a location or organization key (ch_org_).",
    "request_id": "req_3b6e0c2f5a81"
  }
}

The reverse — an organization key on /admin/v1 — fails the same way:

curl https://server.chataigne.ai/admin/v1/organizations \
  -H "x-api-key: ch_org_..."

{
  "error": {
    "type": "authorization_error",
    "code": "wrong_key_surface",
    "message": "An organization key cannot be used on /admin/v1. Use an admin key (ch_admin_).",
    "request_id": "req_d41f8a7c92e0"
  }
}

Every error response carries an X-Request-Id header, mirrored in the body as error.request_id. Include it when contacting support. See Request IDs and Errors.

Key prefixes

Every key carries a prefix that identifies its surface at a glance. The prefix is the only part of a key you should ever expose (for example, in logs or UI): the secret portion that follows must stay confidential.

ch_org_

prefix

Location / organization key. Authenticates the public Chataigne API (/v1). Scoped to a single organization and its locations.

ch_admin_

prefix

Admin key. Authenticates the Admin API (/admin/v1). Performs account-level provisioning across organizations and locations.

Use the prefix to fail fast in your own code. If a key destined for /v1 does not start with ch_org_, you can reject it before making a network call — saving a round-trip and a 403.

Keeping keys safe

API keys grant full programmatic access to your data. A leaked ch_admin_ key in particular can manage organizations and locations across your account.

Never embed API keys in browsers, mobile apps, or any client-side code. Anything shipped to a user’s device is recoverable — view source, DevTools, and binary inspection all expose embedded secrets. Keys belong only on servers you control.

Recommended practices:

Store in environment variables

Load keys from environment variables or a secrets manager. Never hard-code them or commit them to version control.

Call from your backend

Proxy all Chataigne API calls through your own server. The key never reaches the client.

Use least privilege

Reach for an ch_org_ key whenever account-level access is not required. Reserve ch_admin_ keys for provisioning workflows.

Rotate on exposure

If a key is ever exposed — in a log, a screenshot, or a repo — rotate it immediately and audit recent activity.

A typical secure setup keeps the key server-side and exposes only the data your client needs:

Node.js (server-side)

// Runs on your server — the key never reaches the browser.
import express from "express";

const app = express();

app.get("/api/locations", async (_req, res) => {
  const response = await fetch("https://server.chataigne.ai/v1/locations", {
    headers: { "x-api-key": process.env.CHATAIGNE_API_KEY },
  });
  res.status(response.status).json(await response.json());
});

Quick reference

# Public API: list locations (organization key)
curl https://server.chataigne.ai/v1/locations \
  -H "x-api-key: ch_org_..."

# Public API: retrieve one organization (organization key)
curl https://server.chataigne.ai/v1/organizations/org_... \
  -H "x-api-key: ch_org_..."

# Admin API: list organizations (admin key)
curl https://server.chataigne.ai/admin/v1/organizations \
  -H "x-api-key: ch_admin_..."

x-api-key

header

required

Your API key. Use a ch_org_ key for /v1 and a ch_admin_ key for /admin/v1. Required on every request.

Next steps

Errors

Error types, status codes, and response shape.

Request IDs

Trace any request with X-Request-Id.

Rate limits

Per-key, per-surface limits and headers.

Versioning

Path-based major versions and breaking-change policy.

​Authenticating a request

​The two surfaces

Chataigne API

Admin API

​Public API — /v1

​Admin API — /admin/v1

​Strict surface separation

​Missing key → 401

​Wrong key type → 403

​Key prefixes

​Keeping keys safe

Store in environment variables

Call from your backend

Use least privilege

Rotate on exposure

​Quick reference

​Next steps

Errors

Request IDs

Rate limits

Versioning

Authenticating a request

The two surfaces

Public API — `/v1`

Admin API — `/admin/v1`

Strict surface separation

Missing key → 401

Wrong key type → 403

Key prefixes

Keeping keys safe

Quick reference

Next steps