> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/get-started/choose-your-auth.md).

# 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](/knowledge-ai/authentication/api-keys.md)                  | [Instance API — Orchestrator](/knowledge-ai/sources-and-ingestion/instance-api/orchestrator.md) (first ingestion call) |
| Backend automating organization, audit, or retrieval workflows with a role                                                                      | Organization API key → Bearer JWT | [Organization API keys](/knowledge-ai/authentication/organization-api-keys.md) | Create a key in the K-AI Studio portal, then exchange it                                                               |
| MCP client (Claude Desktop / Cursor / Le Chat) or custom user-level integration spanning multiple instances                                     | OAuth 2.1 (Bearer JWT)            | [OAuth 2.1](/knowledge-ai/authentication/oauth.md)                             | [Quickstart — K-AI MCP](/knowledge-ai/get-started/mcp-quickstart.md) (first MCP install)                               |
| 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        | [Cookies](/knowledge-ai/authentication/cookies.md)                             | [K-AI Audit web app](https://app.kai-studio.ai) (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.
* **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.