Organization API keys

When to use: see 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.

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, 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	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 — and is accepted on every platform API that takes a Bearer token.

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.

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.

2. Exchange the key for a token

Post the raw key to the token endpoint. No other credential is required.

curl

curl -X POST https://back.kai-studio.ai/core/api-key/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "ks_org_REDACTED"}'

Python

TypeScript

Response:

{
  "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).

curl

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": "<instance-id>"}'

Python

TypeScript

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.

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.

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.

• 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.