Autonomous agents (API key)

MCP's default authentication is OAuth 2.1, which puts a human at a consent screen. A fully autonomous agent platform has nobody to click it — so the OAuth dance either blocks the integration or, worse, leaves the agent hanging on a browser window that will never open.

For those callers, both K-AI MCP servers accept an Organization API key directly in the Authorization header:

Authorization: Bearer ks_org_REDACTED

No OAuth, no browser, no token-exchange step. The key is a long-lived credential carrying organization roles; everything downstream — group RBAC, per-instance visibility, instructions, and the audit trail — behaves exactly as it does for a user token.

Where the raw key is accepted

Surface	Raw ks_org_… in Authorization: Bearer
Retrieval MCP — https://api-retrieval.kai-studio.ai/mcp	Yes
Audit MCP — https://api-audit.kai-studio.ai/mcp	Yes
Retrieval API (REST) — api-retrieval.kai-studio.ai	Yes
Audit API (REST) — api-audit.kai-studio.ai	Yes
Platform API — back.kai-studio.ai	No — exchange the key for a Bearer token first
Instance API — api.kai-studio.ai	No — uses Instance API keys (instance-id + api-key)

The key is read from the Authorization header only. It is never accepted in a cookie — a long-lived secret does not belong in one.

Exchanging the key for a short-lived Bearer token still works everywhere and remains the right choice when your platform can hold a token cache. Sending the key directly trades that for one less moving part, which is usually what an agentic platform wants.

1. Create the key

Organization administrators create keys from the K-AI Studio portal → Organization → API keys → Create key. Grant the minimum roles the agent needs and copy the ks_org_… value — it is shown once.

Store it in a secret manager on the agent platform's server side. See Organization API keys → Roles for what each role grants.

2. Grant the key access

A key with valid credentials and no access reaches nothing. Both surfaces are fail-closed, and each grants access its own way.

Retrieval

The key must belong to a retrieval group that contains at least one enabled, deployed knowledge base. This holds regardless of the roles the key carries — even ADMIN reaches no knowledge base through Retrieval without a group. An administrator adds it in the portal: Organization → Activate → Groups → pick a group → API keys. Keys appear in the member list with an API key badge.

Until then, retrieval_instances_list_available_instances returns an empty instances array plus a notice field explaining why:

{
  "response": {
    "persona": null,
    "instances": [],
    "relationships": [],
    "notice": "No knowledge base is accessible to this identity. An organization administrator must add this user or API key to a retrieval group that contains at least one enabled, deployed knowledge base."
  }
}

That notice is the single most common symptom of a key plugged in before it was put in a group. The tool takes no arguments, so there is no other query to try and no knowledge base id to guess — relay the notice and stop.

Audit

A key holding ADMIN or STEWARD sees and resolves every Clean item across the organization's audit instances. A key holding KNOWLEDGE_EXPERT needs to be added to an audit instance's team, and is then scoped to that instance. AUTHORITY_MANAGER, ACTIVATION_MANAGER, BILLING, and CONSUMER grant no Clean access on their own.

3. Connect

curl

curl -s -X POST https://api-retrieval.kai-studio.ai/mcp \
  -H "Authorization: Bearer $KAI_ORG_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2025-03-26",
        "capabilities":{},
        "clientInfo":{"name":"autonomous-agent","version":"1.0.0"}}}'

Python

import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    headers = {"Authorization": f"Bearer {os.environ['KAI_ORG_KEY']}"}
    async with streamablehttp_client(
        "https://api-retrieval.kai-studio.ai/mcp", headers=headers
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool(
                "retrieval_instances_list_available_instances", {}
            )
            print(result.content)

asyncio.run(main())

TypeScript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api-retrieval.kai-studio.ai/mcp"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.KAI_ORG_KEY}` },
    },
  },
);

const client = new Client({ name: "autonomous-agent", version: "1.0.0" });
await client.connect(transport);

const result = await client.callTool({
  name: "retrieval_instances_list_available_instances",
  arguments: {},
});
console.log(result.content);

Swap the host for https://api-audit.kai-studio.ai/mcp to drive the Audit tools with the same key.

Error contract

The authentication path returns exactly two failure codes, and they mean opposite things. Wire your retry logic to this distinction — it is the contract, not an implementation detail.

Code	Meaning	What the agent should do
401	The key is invalid, revoked, or expired — or the deployment does not accept keys in Bearer.	Stop. Surface the failure to an operator. Do not retry, and do not fall back to OAuth.
503	Authentication is momentarily unavailable or saturated. The credential is not implicated. A Retry-After header carries the delay.	Retry after Retry-After seconds.

Never treat 401 as a signal to start OAuth. MCP hosts do exactly that: a 401 sends them to /.well-known/oauth-authorization-server and into an Authorization Code flow that requires a browser. An autonomous agent has no browser, so it hangs instead of failing. Treat 401 as fatal and report it.

Once authenticated, the usual per-tool codes apply — 403 for an instance the key's roles cannot reach, 400 for a malformed identifier, 422 for a schema violation. See Errors & status codes.

Lifecycle

• Revocation. Revoking a key in the portal stops it authenticating new callers. Revocation is not instantaneous: allow a short propagation delay, and note that any Bearer token already minted from the key stops working when it expires. Plan for a short tail rather than an instant cut.

• Expiry. A key past its expires_at returns 401. Set one where the integration's lifetime is known.

• Rotation. Create the replacement key, add it to the same groups and teams, deploy it, then revoke the old one. Both keys are live in between, so there is no gap.

• One key per integration. Separate keys let you revoke one agent platform without disrupting the others, and keep the audit trail readable — every call is attributed to the key that made it.

Where to next

• Organization API keys — the full auth model, roles, and the token-exchange alternative.

• Retrieval tools · Audit tools — the tool catalogs.

• Cookbook — multi-tool recipes.

• Connect a client — for interactive clients with a human present.