Agent keys and dashboard tokens

Kordio Control has two callers, and they authenticate differently because they are trusted differently. An agent able to widen its own limits is not governed by them, so the separation is the point rather than a formality.

Caller	Credential	Reaches
An agent, asking whether it may act	Agent API key, `krt_...`	`/control/v1/agent/*`
A person or your backend, managing the workspace	Identity bearer token	`/control/v1/workspaces/{slug}/*`

An agent key can never write policy, and a dashboard token can never authorize an action as an agent.

Integrating the ledger instead? It uses OAuth 2.0 client credentials, documented on Ledger: OAuth client credentials. Nothing on this page applies there.

Getting your credentials

Everything below needs a workspace and a dashboard token, so start here.

Sign up at app.kordio.io and create a workspace. You become its owner, which carries every capability.
Your workspace slug is the one in the console URL: app.kordio.io/{slug}. It is the {workspace_slug} path segment in every management call.
Your dashboard token is the identity token the console holds after sign-in. For scripting, mint one directly:

curl -X POST https://api.kordio.io/control/v1/auth/signin \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "..."}'

200 OK

{
  "data": {
    "access_token": "eyJhbGciOi...",
    "refresh_token": "...",
    "user": { "id": "...", "email": "[email protected]" }
  }
}

access_token is the dashboard token. It is short-lived; exchange the refresh_token at POST /v1/auth/refresh rather than re-sending credentials. If your account has MFA enabled, sign-in answers 401 with code mfa_required and a pending_authentication_token to complete at POST /v1/auth/verify_mfa.

A dashboard token carries your full capability set in the workspace. It is not an agent credential and must never be given to an agent. Agents get an agent key, which cannot write policy.

Set both for the rest of the docs:

Agent keys

This is the credential your agent carries. Create an agent and the key is returned exactly once:

curl -X POST https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/agents \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "procurement agent", "mode": "test", "scopes": ["payment.*"]}'

const res = await fetch(
  `https://api.kordio.io/control/v1/workspaces/${process.env.KORDIO_WORKSPACE}/agents`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KORDIO_DASHBOARD_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "procurement agent",
      mode: "test",
      scopes: ["payment.*"],
    }),
  },
);
const { data } = await res.json();

import os, requests

res = requests.post(
    f"https://api.kordio.io/control/v1/workspaces/{os.environ['KORDIO_WORKSPACE']}/agents",
    headers={"Authorization": f"Bearer {os.environ['KORDIO_DASHBOARD_TOKEN']}"},
    json={"name": "procurement agent", "mode": "test", "scopes": ["payment.*"]},
)
data = res.json()["data"]

201 Created

{
  "data": {
    "id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "name": "procurement agent",
    "status": "active",
    "mode": "test",
    "scopes": ["payment.*"],
    "api_key_prefix": "krt_test_9f3",
    "api_key": "krt_test_9f3a1c7e42b8d05a6e1f8c3d",
    "last_used_at": null,
    "created_at": "2026-08-22T09:04:11Z",
    "starter_policy": {
      "id": "a05f8c37-6b12-4d94-8207-c3e1b9d6a4f8",
      "status": "active",
      "mode": "blocklist",
      "per_transaction_cap_cents": 50000,
      "approval_threshold_cents": 10000,
      "imports": [],
      "rules": []
    }
  }
}

Kordio stores only a digest and compares it in constant time. api_key cannot be shown again; if you lose it, rotate the agent. Keys are prefixed by mode, krt_test_... or krt_live_..., so a test key can never reach live data. The agent arrives with an active starter_policy:

500 on a single action, and anything over

100 held for a person. It governs from the first request, and it keeps governing until you disable it, so a threshold you write later does not replace it. Send "skip_starter_policy": true to create an agent with nothing attached, which denies everything with no_policy until you write a rule. Send it as a bearer token:

curl -X POST https://api.kordio.io/control/v1/agent/actions \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Idempotency-Key: order-4471" \
  -H "Content-Type: application/json" \
  -d '{"budget_id": "3f1c...", "action_type": "payment.create", "cost_cents": 12000}'

Scopes

scopes restricts which action types a key may even ask about: an exact match (payment.create), a namespace wildcard (payment.*), or *. An empty array means unrestricted. A request outside the key’s scopes is refused by an intrinsic rule before any policy runs, and the decision names runtime_scope as what refused it. Scope narrowly, and use one agent per workload. A key shared across two workloads buys you nothing and costs you the ability to revoke one of them without stopping the other.

Rotating and revoking

An agent is active, suspended, or revoked, changed with PATCH /control/v1/workspaces/{slug}/agents/{id}. Suspending stops new authorizations and leaves history intact; revoking is permanent. Neither rewrites decisions already made, and neither invalidates a cosignature already issued, which stays verifiable until it expires. Cosignature lifetime is minutes, so that window is small, but it is not zero. See what Kordio guarantees.

Dashboard tokens and capabilities

Everything under /control/v1/workspaces/{slug}/* uses the identity token: creating agents, writing policy, reading intents, resolving approvals, managing billing.

curl https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/policies \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN"

Capabilities come from your role in that workspace, and the API enforces them:

Role	Capabilities
`owner`	`read`, `approve`, `manage_policy`, `manage_members`
`admin`	`read`, `approve`, `manage_policy`
`member`	`read`

Capability	Lets you
`read`	See agents, policies, budgets, intents, funds, the audit trail
`approve`	Resolve a held action
`manage_policy`	Write policy, create and rotate agents, manage webhook endpoints
`manage_members`	Invite and remove people, change roles, manage billing, delete the workspace

approve and manage_policy are deliberately separate. The person who authorises a payment need not be the person who can widen the rule that held it, which is most of what an auditor is looking for. Every role can read the audit trail, including member. An audit trail only some people can see is not much of one.

Test and live

Every credential is bound to one mode and the two never mix. A test agent key cannot touch live data, and a live agent cannot be created on a plan without live mode. Test mode runs the same policy engine, returns the same shapes, and issues real cosignatures. That is deliberate: you can prove an entire integration, including signature verification inside your own executor, before any money is at stake. Control-plane responses carry no livemode field. The mode is a property of the agent, so read it from GET /control/v1/workspaces/{slug}/agents/{id}, or from agent_mode inside a decision. The ledger API does echo livemode on every response, so do not write one client that assumes both.

When something is refused

Status	Meaning
`401`	Missing (`runtime_key_required`) or unrecognised (`invalid_runtime_key`) credential.
`403`	Recognised but not permitted: a capability you lack (`insufficient_role`), or a decision that was denied.
`404`	The resource exists but not in a workspace or agent you can reach. Kordio does not confirm existence across a tenancy boundary.

A 404 where you expected a 403 is usually a workspace or agent mismatch, not a missing record.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

Agent keys and dashboard tokens

Getting your credentials

Agent keys

Scopes

Rotating and revoking

Dashboard tokens and capabilities

Test and live

When something is refused

Next steps

Authorize an agent action

Errors

​Getting your credentials

​Agent keys

​Scopes

​Rotating and revoking

​Dashboard tokens and capabilities

​Test and live

​When something is refused

​Next steps

Authorize an agent action

Errors

Getting your credentials

Agent keys

Scopes

Rotating and revoking

Dashboard tokens and capabilities

Test and live

When something is refused

Next steps