A small surface, deliberately.

Authentication

Every request carries a bearer credential that resolves to an agent and an org. The org_id in a request body is checked against the credential — it is not trusted as an assertion. A mismatch is denied and recorded.

Console keys and SCIM tokens are separate credential surfaces. A SCIM token cannot be used as a console key; that separation is enforced by test.

Where the decision happens

Not here. This is the part of the API most likely to be misread, so it is worth being blunt about: the control plane does not authorize actions over HTTP. There is no endpoint you call to ask permission.

Decisions are made locally, in-process, by the engine — the SDK wrapper, the gateway, or the runtime, whichever is in front of your agent. That is deliberate. An authorization hop over the network would put a remote dependency on the path of every tool call an agent makes, and a control plane that is unreachable would then have to either fail open or stop your agents. Evaluating locally means a network partition costs you telemetry, not enforcement.

import { guard } from "@cirvix_ai/agent-control";

// Evaluated in-process, against the policy this workspace has loaded.
// No network call is made to reach a verdict.
const readFile = guard.wrap(fs.readFile, { tool: "fs.read" });

await readFile("./.env");   // throws: deny-dotenv-read

What reaches this API afterwards is the record of a decision that has already been made and enforced.

Reporting decisions

POST /v1/decisions — ingest decisions the engine already made. This is telemetry, metering and the audit trail; it is not an authorization call, and the verdict is a field you send, not one you receive.

{
  "decisions": [{
    "verdict":  "deny",
    "tool":     "fs.read",
    "resource": "./.env",
    "rule":     "deny-dotenv-read",
    "reason":   "secrets are brokered, not read",
    "agent":    "pr-triage",
    "runId":    "run_4c07e2"
  }]
}

Send one decision as a bare object, or up to 500 in a decisions array — more than that is refused with 413 before anything is stored, so a rejected batch never leaves you guessing which half landed. The org_id is taken from your credential and never from the body.

A tenant past its daily allowance with no credits gets 402, and nothing in that batch is recorded. Note what this does not do: it cannot un-enforce anything. The action was already permitted or blocked locally at the moment it happened. A 402 here means you lose the record, not the protection.

Endpoints

Verdicts

Errors