API keys and permissions - Chataigne Docs

Every Chataigne API request must include a Chataigne API key in the x-api-key header.

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

Keys begin with ch_org_. The prefix identifies the credential type; the complete value is secret.

Keep API keys on servers you control. Do not embed them in websites or mobile applications, commit them to source control, or write them to logs. Store them in an environment variable or secret manager and rotate them if exposed.

Scope and permissions

Access is controlled by two independent rules:

Scope determines which organization or locations the key can reach.
Permissions determine which actions the key can perform on those resources.

A request succeeds only when the resource is in scope and the key has the endpoint’s required permission.

Business-organization-scoped keys

A key scoped to a business organization can reach that organization and its child locations. For example:

GET /v1/organizations returns the organization.
GET /v1/locations returns the organization’s accessible locations.
A request for a location outside that organization is rejected.

Location-scoped keys

A key scoped to a location can reach only that location. It cannot access a parent organization or another location. For example:

GET /v1/locations returns the key’s location.
GET /v1/organizations returns an empty list.
A request for a sibling location is rejected.

A standalone location has no parent organization. A location-scoped key works the same way whether or not its location belongs to an organization.

Common permissions

Permissions use the form resource.action. Your Chataigne contact configures them when issuing a key.

Permission	Allows
`businessOrganization.read`	List and retrieve the business organization in scope.
`businessOrganization.update`	Update the business organization’s profile.
`location.read`	List and retrieve locations in scope.
`location.create`	Create a location inside the business organization in scope.
`location.update`	Update a location’s profile.
`orderSettings.read` / `orderSettings.write`	Read or change order settings.
`openingHoursSettings.read` / `openingHoursSettings.write`	Read or change opening hours and special closings.
`deliverySettings.read` / `deliverySettings.write`	Read or change delivery settings.
`locationStatusSettings.read` / `locationStatusSettings.write`	Read or change order acceptance.
`ai.read` / `ai.write`	Read or change AI clerk instructions.
`analytics.read`	Retrieve analytics.

Grant only the permissions your integration needs. A read-only reporting integration, for example, does not need any write, update, or create permission.

Authentication errors

Status	Meaning
`401 authentication_error`	The `x-api-key` header is missing, malformed, expired, or otherwise invalid.
`403 authorization_error`	The key is valid, but its scope or permissions do not allow the request.
`404 not_found_error`	The requested resource does not exist or is not available to the key.

Error bodies include a request ID:

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permission",
    "message": "This API key does not have permission to perform this action.",
    "request_id": "req_9c4a1e22"
  }
}

Log the X-Request-Id response header, but never the API key itself. Include the request ID when asking Chataigne support to investigate a call.

Next step

Use Find your resources to see how each key scope affects organization and location discovery.

​Scope and permissions

​Business-organization-scoped keys

​Location-scoped keys

​Common permissions

​Authentication errors

​Next step

Scope and permissions

Business-organization-scoped keys

Location-scoped keys

Common permissions

Authentication errors

Next step