For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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 → OrganizationAPI keysCreate 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.

2. Exchange the key for a token

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

Response:

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

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.

Last updated