Authorize an agent action

By the end of this page an agent of yours asks Kordio before it spends, and Kordio answers allowed, requires_approval, or denied, naming the rule that decided.

Wrong page? This gates what an agent is allowed to spend, before it spends it. If you are here to post double-entry transactions and read balances, you want the Ledger quickstart instead.

Everything here runs in test mode, which uses the same policy engine as live, so the integration you write now is the one you ship.

0. Get your credentials

Sign up at app.kordio.io, create a workspace, and mint a dashboard token. The full walkthrough is on getting your credentials.

1. Create an agent

An agent is a scoped identity for one workload. It carries its own API key and its own permitted action types.

AGENT=$(curl -s -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.*","tool.invoke"]}')

export KORDIO_AGENT_ID=$(echo "$AGENT" | jq -r '.data.id')
export KORDIO_AGENT_KEY=$(echo "$AGENT" | jq -r '.data.api_key')
export KORDIO_STARTER_POLICY_ID=$(echo "$AGENT" | jq -r '.data.starter_policy.id')

201 Created

{
  "data": {
    "id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "name": "procurement agent",
    "status": "active",
    "mode": "test",
    "scopes": ["payment.*", "tool.invoke"],
    "max_budget_cents": 100000,
    "api_key_prefix": "krt_test_9f3",
    "api_key": "krt_test_9f3a1c7e42b8d05a6e1f8c3d",
    "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": []
    }
  }
}

api_key is returned exactly once and starts with krt_test_. Store it the way you store any other secret; Kordio keeps only a digest and cannot show it to you again. scopes restricts which action types this key may even ask about. An empty array means unrestricted, not blocked. Name the action types you expect, and keep one agent per workload so you can revoke one without stopping the rest. Read starter_policy before you go further. A new agent arrives governed rather than open: a single action is capped at

500, and anything over

100 is held for a person. Nothing you write later replaces it, so step 2 retires it. Pass "skip_starter_policy": true to create an agent with no policy at all, which denies everything until you write one.

2. Write your own policy

The starter policy is a floor, not the policy you want. Write yours alongside it:

curl -X POST https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/policies \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$KORDIO_AGENT_ID\",
    \"per_transaction_cap_cents\": 50000,
    \"approval_threshold_cents\": 200000,
    \"velocity_cap_cents\": 200000,
    \"velocity_window_seconds\": 3600
  }"

That policy says: never more than

500 in one action, hold anything over

2,000 for a person, and never more than $2,000 in any rolling hour. The third rule is the one that catches a retry loop. The first two, on their own, would let nineteen individually reasonable $340 charges through. Both policies are active now, and both run. Where two rules answer the same question the tighter one decides, so the starter’s

100 threshold would still govern, not your

2,000 one. Retire it now that your rules cover its ground:

curl -X PATCH \
  https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/policies/$KORDIO_STARTER_POLICY_ID \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "disabled"}'

200 OK

{ "data": { "id": "a05f8c37-6b12-4d94-8207-c3e1b9d6a4f8", "status": "disabled" } }

Do that in this order, and never disable an agent’s last active policy. An agent with no active policy denies everything, with the rule no_policy. That is deliberate and fail-closed: an agent nobody has written rules for has no authority rather than unlimited authority.

3. Open a budget

A budget is the envelope for one run. Every authorized action commits against it, which makes it the thing that stops a loop rather than a single mistake.

BUDGET=$(curl -s -X POST https://api.kordio.io/control/v1/agent/budgets \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"budget_cents": 50000, "currency": "USD"}')

export KORDIO_BUDGET_ID=$(echo "$BUDGET" | jq -r '.data.id')

const res = await fetch("https://api.kordio.io/control/v1/agent/budgets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KORDIO_AGENT_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ budget_cents: 50_000, currency: "USD" }),
});
const { data: budget } = await res.json();

import os, requests

res = requests.post(
    "https://api.kordio.io/control/v1/agent/budgets",
    headers={"Authorization": f"Bearer {os.environ['KORDIO_AGENT_KEY']}"},
    json={"budget_cents": 50_000, "currency": "USD"},
)
budget = res.json()["data"]

201 Created

{
  "data": {
    "id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
    "agent_id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "parent_budget_id": null,
    "budget_cents": 50000,
    "spent_cents": 0,
    "remaining_cents": 50000,
    "currency": "USD",
    "status": "active",
    "created_at": "2026-08-04T09:11:52Z"
  }
}

4. Ask before you spend

This is the call that matters. Put it in front of the action, not after it.

ACTION=$(curl -s -w '\n%{http_code}' -X POST https://api.kordio.io/control/v1/agent/actions \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Idempotency-Key: order-4471-attempt-1" \
  -H "Content-Type: application/json" \
  -d "{
    \"budget_id\": \"$KORDIO_BUDGET_ID\",
    \"action_type\": \"payment.create\",
    \"resource\": \"acme-supplies.example\",
    \"cost_cents\": 12000
  }")

export KORDIO_ACTION_ID=$(echo "$ACTION" | head -n-1 | jq -r '.data.id')
echo "$ACTION" | tail -n1   # the status code you branch on

const res = await fetch("https://api.kordio.io/control/v1/agent/actions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KORDIO_AGENT_KEY}`,
    "Idempotency-Key": "order-4471-attempt-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    budget_id: budget.id,
    action_type: "payment.create",
    resource: "acme-supplies.example",
    cost_cents: 12_000,
  }),
});

const body = await res.json();
switch (res.status) {
  case 201: /* execute, then report in step 5 */ break;
  case 202: /* held for a person. stop and wait */ break;
  case 403: /* denied. do not execute */ break;
}

res = requests.post(
    "https://api.kordio.io/control/v1/agent/actions",
    headers={
        "Authorization": f"Bearer {os.environ['KORDIO_AGENT_KEY']}",
        "Idempotency-Key": "order-4471-attempt-1",
    },
    json={
        "budget_id": budget["id"],
        "action_type": "payment.create",
        "resource": "acme-supplies.example",
        "cost_cents": 12_000,
    },
)
body = res.json()
# 201 execute, 202 held for a person, 403 denied

201 Created

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
    "action_type": "payment.create",
    "resource": "acme-supplies.example",
    "cost_cents": 12000,
    "currency": "USD",
    "state": "pending",
    "trace_id": "5e8c1a47-2b93-4d06-a7f1-9c3e05b8d24a",
    "created_at": "2026-08-22T09:12:04Z"
  },
  "decision": {
    "outcome": "allowed",
    "rule": null,
    "detail": {},
    "headroom": {
      "session_remaining_cents": 50000,
      "per_action_cap_cents": 50000,
      "approval_threshold_cents": 200000,
      "velocity_cap_remaining_cents": 200000
    },
    "policy_snapshot": [
      {
        "id": "c41d7b28-9e05-4a63-b7f1-6d2c8e30a915",
        "status": "active",
        "mode": "blocklist",
        "imports": [],
        "per_transaction_cap_cents": 50000,
        "approval_threshold_cents": 200000,
        "velocity_cap_cents": 200000,
        "velocity_window_seconds": 3600,
        "monthly_cap_cents": null,
        "counterparty_allowlist": [],
        "rules": []
      }
    ]
  },
  "cosignature": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8xIn0..."
}

policy_snapshot carries every active policy. Leave the starter enabled and it appears here too, with headroom reduced to the tightest value per key, which is how a threshold you wrote can be quietly overruled by one you did not. Read the status code, not the body, to branch:

Status	Outcome	What your agent does
`201`	`allowed`	Execute, then report the result in step 5.
`202`	`requires_approval`	Stop. A person has to resolve it. Poll `GET /control/v1/agent/actions/{id}` or wait for your webhook. Do not call `complete`: it is a `422` from any state but `pending`.
`403`	`denied`	Do not execute. `decision.rule` names what refused.

Idempotency-Key is required, and its absence is a 422, not a 400. Reuse the same key when you retry and Kordio replays the original decision instead of reserving the budget twice. The key is matched on its own: a replay returns the first decision even if you changed the amount or the counterparty underneath it, so give a genuinely different action a genuinely different key. decision.headroom reports what every limit had left, and decision.policy_snapshot is the policy exactly as it read at that moment. Both are measured before the reservation, so session_remaining_cents above is still the full $500: subtract cost_cents yourself for the figure after this action. Surface headroom to your agent so it can pick a cheaper path instead of retrying into the same wall. Raise cost_cents past your $2,000 threshold and this call answers 202 instead, with no cosignature. That is the product working, not a failure. See holding spend for a person for what happens next.

5. Report what happened

Kordio holds the budget reservation until you say how the action ended.

curl -X POST \
  https://api.kordio.io/control/v1/agent/actions/$KORDIO_ACTION_ID/complete \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY"

If it failed, say so instead. The reservation is released and the budget goes back:

curl -X POST \
  https://api.kordio.io/control/v1/agent/actions/$KORDIO_ACTION_ID/fail \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "vendor returned 502"}'

Skipping this step is the most common integration mistake, and nothing sweeps up after it. A budget has no expiry and no close endpoint, so an action that is never completed or failed holds its share of the budget for good. Open a budget per run and let it end with the run.

Payments report the same way, through POST /control/v1/agent/payment_intents/:id/complete and /fail. Kordio authorizes the spend and hands you a cosignature; your own rail moves the money. See the payments section.

6. Try it without spending anything

simulate runs the whole policy evaluation and records no intent and no reservation. Use it in tests, and in your own UI to show someone what a policy would do before they save it.

curl -X POST https://api.kordio.io/control/v1/agent/actions/simulate \
  -H "Authorization: Bearer $KORDIO_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"budget_id\": \"$KORDIO_BUDGET_ID\",
    \"action_type\": \"payment.create\",
    \"cost_cents\": 999999
  }"

200 OK

{
  "data": {
    "outcome": "denied",
    "rule": "session_budget",
    "detail": { "remaining_cents": 38000, "requested_cents": 999999 },
    "headroom": {
      "session_remaining_cents": 38000,
      "per_action_cap_cents": 50000,
      "approval_threshold_cents": 200000,
      "velocity_cap_remaining_cents": 188000
    },
    "policy_snapshot": [
      { "id": "c41d7b28-9e05-4a63-b7f1-6d2c8e30a915", "status": "active", "mode": "blocklist" }
    ]
  }
}

It always returns 200, whatever the outcome, and the decision has no id because no intent was created. policy_snapshot is abbreviated here; the real one repeats every column of every active policy.

Next steps

Writing a policy

Every rule kind, the typed shorthands, and the condition language.

Verifying an authorization

Check the cosignature offline, in your executor.

Holding spend for a person

What 202 means and how the queue resolves.

API reference

Every field on every endpoint.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

Authorize an agent action

0. Get your credentials

1. Create an agent

2. Write your own policy

3. Open a budget

4. Ask before you spend

5. Report what happened

6. Try it without spending anything

Next steps

Writing a policy

Verifying an authorization

Holding spend for a person

API reference

​0. Get your credentials

​1. Create an agent

​2. Write your own policy

​3. Open a budget

​4. Ask before you spend

​5. Report what happened

​6. Try it without spending anything

​Next steps

Writing a policy

Verifying an authorization

Holding spend for a person

API reference

0. Get your credentials

1. Create an agent

2. Write your own policy

3. Open a budget

4. Ask before you spend

5. Report what happened

6. Try it without spending anything

Next steps