Choose your auth

Four 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

Backend automating organization, audit, or retrieval workflows with a role

Organization API key → Bearer JWT

Create a key in the K-AI Studio portal, then exchange it

Autonomous agent platform driving MCP with no human in the loop

Organization API key sent directly in Authorization: Bearer

Create a key, add it to a retrieval group, point the agent at /mcp

MCP client (Claude Desktop / Cursor / Le Chat) or custom user-level integration spanning multiple instances

OAuth 2.1 (Bearer JWT)

Browser frontend on .kai-studio.ai (K-AI Audit web app, K-AI Studio portal, K-AI Retrieval admin console, K-AI Consumption Monitoring System)

kai_auth HttpOnly cookie

K-AI Audit web app (sign in directly)

Decision rules

Use Instance API keys when the caller is a backend process and the operation is scoped to one instance. No user identity, no group RBAC.
Use Organization API keys when a backend automates organization, audit, or retrieval workflows and needs a role. The key authenticates as a service account; the token it mints is authorized by organization RBAC, exactly like a portal user.
Send an Organization API key directly — raw, in Authorization: Bearer, with no exchange step — when the caller is an unattended agent platform talking to the Audit or Retrieval APIs or their MCP endpoints. OAuth needs a human at a consent screen; an autonomous agent has none. Authorization is unchanged: the key is authorized by the same organization RBAC as any other identity.
Use OAuth 2.1 when the caller acts on behalf of a human user, especially for interactive MCP clients 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.

Last updated 18 days ago