Authorize an action

curl --request POST \
  --url https://api.kordio.io/control/v1/agent/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
  "action_type": "payment.create",
  "resource": "acme-supplies.example",
  "cost_cents": 12000,
  "metadata": {
    "order_id": "4471"
  }
}
'

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "workspace_id": "1c4f8b20-9e77-4a31-b5d2-06a8c3e91f4d",
    "agent_id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
    "action_type": "payment.create",
    "resource": "acme-supplies.example",
    "cost_cents": 12000,
    "currency": "USD",
    "state": "pending",
    "idempotency_key": "order-4471-attempt-1",
    "trace_id": "5e8c1a47-2b93-4d06-a7f1-9c3e05b8d24a",
    "ledger_transaction_id": null,
    "failure_reason": null,
    "resolved_by_sub": null,
    "resolved_at": null,
    "metadata": {
      "order_id": "4471"
    },
    "created_at": "2026-08-04T09:12:04Z",
    "updated_at": "2026-08-04T09:12:04Z"
  },
  "decision": {
    "outcome": "allowed",
    "rule": null,
    "detail": {},
    "headroom": {
      "session_remaining_cents": 38000,
      "monthly_remaining_cents": 188000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": null
  },
  "cosignature": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8xIiwidHlwIjoiSldUIn0"
}

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "state": "requires_approval",
    "action_type": "payment.create",
    "cost_cents": 240000,
    "currency": "USD"
  },
  "decision": {
    "outcome": "requires_approval",
    "rule": "approval_threshold",
    "detail": {
      "threshold_cents": 100000,
      "requested_cents": 240000
    },
    "headroom": {
      "session_remaining_cents": 260000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": {
      "kind": "approve",
      "max_cents": 100000,
      "summary": "Someone has to approve this. Anything at $1000.00 or less clears without approval."
    }
  }
}

{
  "error": {
    "message": "Agent key is required",
    "code": "runtime_key_required"
  }
}

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "state": "denied",
    "cost_cents": 120000
  },
  "decision": {
    "outcome": "denied",
    "rule": "per_transaction_cap",
    "detail": {
      "limit_cents": 50000,
      "requested_cents": 120000
    },
    "headroom": {
      "session_remaining_cents": 380000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": {
      "kind": "lower_amount",
      "max_cents": 50000,
      "summary": "A per-action cap applies. Retry at $500.00 or less."
    }
  }
}

{
  "error": {
    "message": "<string>",
    "code": "runtime_key_required"
  }
}

{
  "error": {
    "message": "Idempotency-Key header is required",
    "code": "idempotency_key_required"
  }
}

{
  "error": {
    "message": "Rate limit exceeded",
    "code": "rate_limited"
  }
}

POST

control

agent

actions

curl --request POST \
  --url https://api.kordio.io/control/v1/agent/actions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
  "action_type": "payment.create",
  "resource": "acme-supplies.example",
  "cost_cents": 12000,
  "metadata": {
    "order_id": "4471"
  }
}
'

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "workspace_id": "1c4f8b20-9e77-4a31-b5d2-06a8c3e91f4d",
    "agent_id": "7d2a6c15-3f89-4b02-9e64-8a15d7c0b3f2",
    "budget_id": "3f1c8a92-5d41-4c8e-9f2b-7a6e1d0c4b83",
    "action_type": "payment.create",
    "resource": "acme-supplies.example",
    "cost_cents": 12000,
    "currency": "USD",
    "state": "pending",
    "idempotency_key": "order-4471-attempt-1",
    "trace_id": "5e8c1a47-2b93-4d06-a7f1-9c3e05b8d24a",
    "ledger_transaction_id": null,
    "failure_reason": null,
    "resolved_by_sub": null,
    "resolved_at": null,
    "metadata": {
      "order_id": "4471"
    },
    "created_at": "2026-08-04T09:12:04Z",
    "updated_at": "2026-08-04T09:12:04Z"
  },
  "decision": {
    "outcome": "allowed",
    "rule": null,
    "detail": {},
    "headroom": {
      "session_remaining_cents": 38000,
      "monthly_remaining_cents": 188000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": null
  },
  "cosignature": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImtleV8xIiwidHlwIjoiSldUIn0"
}

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "state": "requires_approval",
    "action_type": "payment.create",
    "cost_cents": 240000,
    "currency": "USD"
  },
  "decision": {
    "outcome": "requires_approval",
    "rule": "approval_threshold",
    "detail": {
      "threshold_cents": 100000,
      "requested_cents": 240000
    },
    "headroom": {
      "session_remaining_cents": 260000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": {
      "kind": "approve",
      "max_cents": 100000,
      "summary": "Someone has to approve this. Anything at $1000.00 or less clears without approval."
    }
  }
}

{
  "error": {
    "message": "Agent key is required",
    "code": "runtime_key_required"
  }
}

{
  "data": {
    "id": "9b2ef0c1-6a3d-4e75-8c19-2f4b7d5a0e63",
    "state": "denied",
    "cost_cents": 120000
  },
  "decision": {
    "outcome": "denied",
    "rule": "per_transaction_cap",
    "detail": {
      "limit_cents": 50000,
      "requested_cents": 120000
    },
    "headroom": {
      "session_remaining_cents": 380000
    },
    "policy_snapshot": [],
    "policy_version": "pv_8f2c1d0a4b6e93571ac2e8d045f7b312",
    "frame_hash": "fh_1b9a0c7e5d2f483610badc0ffee1234567890abcdef1234567890abcdef123456",
    "remedy": {
      "kind": "lower_amount",
      "max_cents": 50000,
      "summary": "A per-action cap applies. Retry at $500.00 or less."
    }
  }
}

{
  "error": {
    "message": "<string>",
    "code": "runtime_key_required"
  }
}

{
  "error": {
    "message": "Idempotency-Key header is required",
    "code": "idempotency_key_required"
  }
}

{
  "error": {
    "message": "Rate limit exceeded",
    "code": "rate_limited"
  }
}

Authorizations

Authorization

string

header

required

An agent API key, krt_live_... or krt_test_..., shown exactly once at creation. Kordio stores only a digest. This credential can ask for authorization and can never write policy.

Headers

Idempotency-Key

string

required

Unique per action, scoped to the agent. A replay returns the original intent and the original decision, at the original status, rather than reserving budget twice.

Example:

"order-4471-attempt-1"

Body

application/json

budget_id

string<uuid>

required

An active session belonging to this agent.

action_type

string

required

Lowercase, dot separated.

Pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$

Example:

"payment.create"

resource

string | null

The counterparty or target. Matched by allowlists.

Example:

"acme-supplies.example"

cost_cents

integer

default:0

Minor units. Omit or 0 for an action that spends nothing.

Required range: x >= 0

metadata

object

Any dot path here is addressable from the condition language as metadata.*.

trace_id

string | null

Yours if you have one, generated otherwise. Links the whole audit trail.

Response

allowed. Execute the action, then report the outcome with complete or fail. A cosignature is included when cosigning is configured.

data

object

required

Show child attributes

decision

object

required

Show child attributes

cosignature

string

A compact ES256 JWS over the authorization. Present only when the outcome is allowed and cosigning is configured; the key is absent otherwise, never null.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

Authorize an action

Authorizations

Headers

Body

Response