Chatbots & organisations

PAI Chat is multi-tenant. An organisation owns one or more chatbots, and every request resolves to exactly one chatbot. Which chatbot — and which key scope — determines what a request may do.

The model

Organisation — the top-level tenant. Holds members, billing, and its chatbots.
Chatbot — one configured assistant (persona, knowledge, model) inside an organisation.

Key scopes

An API key is locked to a scope at creation and cannot escalate. The scope decides the breadth of access:

Scope	Works for	Required header
Organisation key	Any chatbot in the organisation, plus org-level admin routes	`x-organization-id`
Chatbot key	One chatbot only	`x-chatbot-id`

Identifying the target

Requests carry the ids they act on. The organisation is set by x-organization-id and must match the key's organisation. The chatbot is resolved in this order:

the x-chatbot-id header (explicit — always use this for server-to-server calls);
the request's referer host matched against a chatbot's registered domain (used by browser widget embeds);
a configured default chatbot, as a last resort.

rule

A scope mismatch returns 403 — for example an organisation-scoped key used against a different organisation, or a chatbot key used against a different chatbot. If no chatbot can be resolved at all, the request returns 404 Chatbot not found.

Members & roles

Organisations and chatbots each have members. Creating an organisation key needs organisation-admin permission; creating a chatbot key needs chatbot-admin permission. Invites flow through send → resend → complete, and can be revoked before acceptance.

See Authentication for creating and rotating keys, and Embedding the chat widget for implicit chatbot resolution in the browser.