> 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/authentication/organization-api-keys.md). # Organization API keys {% hint style="info" %} **When to use:** see [Choose your auth](/knowledge-ai/authentication/authentication.md#choose-your-auth) for the decision rule. This page covers the **Organization API key** model — a backend credential that carries an organization role, for automating the K-AI Platform, Audit, and MCP/Retrieval APIs without a browser. {% endhint %} An **Organization API key** lets a backend service call the same platform APIs a user drives from the K-AI Studio portal — scoped to one organization and to the roles you grant the key. Unlike an [Instance API key](/knowledge-ai/authentication/api-keys.md), which has no identity and targets a single KAI instance, an Organization API key authenticates as a **service account** with organization-level roles, so the same role-based access control that governs the web apps applies to it. | | [Instance API key](/knowledge-ai/authentication/api-keys.md) | Organization API key | | -------------- | ------------------------------------------------------------ | ------------------------------------------------------- | | Identity | None | Service account, organization-scoped | | Access control | Full access to one instance | Role-based, same roles as the portal | | Targets | KAI Instance API (`api.kai-studio.ai`) | Platform / Audit / Retrieval APIs | | Credential | static `instance-id` + `api-key` | `ks_org_…` key exchanged for a short-lived Bearer token | ## How it works An Organization API key is a long-lived secret you exchange for a short-lived **Bearer access token**. The token is an ordinary JWT — identical in shape to one obtained via [OAuth 2.1](/knowledge-ai/authentication/oauth.md) — and is accepted on every platform API that takes a Bearer token. ```mermaid sequenceDiagram participant S as Your backend participant B as K-AI Platform API participant R as Audit / Retrieval API S->>B: POST /core/api-key/token (ks_org_… key) B-->>S: access_token (Bearer JWT) S->>R: API call with Authorization: Bearer R-->>S: Response (scoped to the key's role) ``` ## 1. Create a key Organization administrators create keys from the K-AI Studio portal → **Organization** → **API keys** → **Create key**. Choose a name, the **roles** the key should carry, and an optional expiry. The raw key is shown **once**, at creation, in the form `ks_org_…`. Store it immediately; it cannot be retrieved later. {% hint style="warning" %} Grant a key the **minimum roles** it needs. A leaked key has the full access of the roles it carries within its organization — treat it like a password. Rotate and revoke from the same screen. {% endhint %} ## 2. Exchange the key for a token Post the raw key to the token endpoint. No other credential is required. {% tabs %} {% tab title="curl" %} ```bash curl -X POST https://back.kai-studio.ai/core/api-key/token \ -H "Content-Type: application/json" \ -d '{"api_key": "ks_org_REDACTED"}' ``` {% endtab %} {% tab title="Python" %} ```python import httpx resp = httpx.post( "https://back.kai-studio.ai/core/api-key/token", json={"api_key": "ks_org_REDACTED"}, ) token = resp.json()["access_token"] ``` {% endtab %} {% tab title="TypeScript" %} ```typescript const resp = await fetch("https://back.kai-studio.ai/core/api-key/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ api_key: "ks_org_REDACTED" }), }); const { access_token } = await resp.json(); ``` {% endtab %} {% endtabs %} Response: ```json { "access_token": "eyJ...REDACTED", "token_type": "bearer", "expires_in": 3600 } ``` The token is short-lived. When it expires, exchange the key again — there is no refresh token for this flow. ## 3. Call the API Send the access token as a Bearer credential. The same token is accepted on the K-AI Platform API, the Audit API (`api-audit.kai-studio.ai`), and the Retrieval API (`api-retrieval.kai-studio.ai`). {% tabs %} {% tab title="curl" %} ```bash curl -X POST https://api-retrieval.kai-studio.ai/retrieval/semantic-nodes/search \ -H "Authorization: Bearer eyJ...REDACTED" \ -H "Content-Type: application/json" \ -d '{"query": "What are the safety requirements?", "instance_id": ""}' ``` {% endtab %} {% tab title="Python" %} ```python import httpx resp = httpx.post( "https://api-retrieval.kai-studio.ai/retrieval/semantic-nodes/search", headers={"Authorization": f"Bearer {token}"}, json={"query": "What are the safety requirements?", "instance_id": ""}, ) ``` {% endtab %} {% tab title="TypeScript" %} ```typescript const resp = await fetch( "https://api-retrieval.kai-studio.ai/retrieval/semantic-nodes/search", { method: "POST", headers: { "Authorization": `Bearer ${access_token}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "What are the safety requirements?", instance_id: "", }), }, ); ``` {% endtab %} {% endtabs %} ## Roles A key carries one or more organization roles. The token it produces is authorized exactly as a portal user holding those roles would be — an endpoint the role cannot use returns `403`. | Role | Grants, in practice | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `ADMIN` | Full organization administration: members, instances, keys, and every workflow below. The broadest role assignable to a key. | | `AUTHORITY_MANAGER` | View and create instances; define governance scope and run governance operations. | | `STEWARD` | Governance operations plus the full Clean workflow (view, resolve, manage). | | `KNOWLEDGE_EXPERT` | View and resolve Clean items on the instances they belong to. | | `ACTIVATION_MANAGER` | Manage MCP/Retrieval exposure for the organization. | | `BILLING` | View billing information. | | `CONSUMER` | Organization access only — read-level membership. | {% hint style="info" %} **`ORG_OWNER` cannot be assigned to a key**, and keys never hold platform-wide administrator rights. A key's reach is bounded by its organization and its roles — nothing more. {% endhint %} ## Lifecycle & security * **Scope to the minimum.** One key, one purpose, the fewest roles. Create separate keys for separate integrations so you can revoke one without disrupting the rest. * **Server-side only.** Never embed an Organization API key — or a token derived from it — in browsers, mobile apps, or any client-side code. It is a machine-to-machine credential. * **Expiry.** Set an `expires_at` where you can; a key past its expiry stops minting tokens. * **Revoke.** Revoking a key from the portal disables it immediately; tokens already issued stop working as they expire (minutes), and the key can mint no new ones. * **Rotation.** To rotate, create a new key, deploy it, then revoke the old one. ## Which key do I need? * Pipeline that only ingests documents into a single instance, no user identity → [Instance API keys](/knowledge-ai/authentication/api-keys.md). * Backend automating organization, audit, or retrieval workflows with a role → **Organization API keys** (this page). * Anything acting on behalf of a human, including MCP clients → [OAuth 2.1](/knowledge-ai/authentication/oauth.md).