Choose your auth

Three auth surfaces; pick by caller type.

Caller type	Auth	Documentation	Next step
Backend pipeline ingesting documents into a single instance	instance-id + api-key headers	Instance API keys	Instance API — Orchestrator (first ingestion call)
MCP client (Claude Desktop / Cursor / Le Chat) or custom user-level integration spanning multiple instances	OAuth 2.1 (Bearer JWT)	OAuth 2.1	Quickstart — K-AI MCP (first MCP install)
Browser frontend on .kai-studio.ai (K-AI Audit web app, K-AI Studio portal, K-AI Retrieval admin console, PICSOU dashboard)	kai_auth HttpOnly cookie	Cookies	K-AI Audit web app (sign in directly)

Decision rules

• Use API keys when the caller is a backend process and the operation is scoped to one instance. No user identity, no group RBAC.

• Use OAuth 2.1 when the caller acts on behalf of a human user, especially for MCP and cross-instance queries. Tokens are scoped to the user's access rights.

• Use cookies only for browser frontends served from *.kai-studio.ai. Never read/write the cookie from JavaScript — it's HttpOnly by design.