API reference

Decide whether an agent may act, and optionally execute what was allowed.

Auth: API key

Request

{
  "agent":    "did:key:z6Mk…",          // required
  "permit":   "<permit artifact>",       // required
  "action":   "purchase",                // required, ≤ 64 chars
  "resource": "resource://company/procurement/laptop",  // required, ≤ 512
  "amount":   { "minor": 500000, "currency": "TRY" },   // optional
  "intent":   "<intent id>",             // optional

  // At most ONE of these. Both together is refused: an execution calls a
  // merchant and a chain authorization issues an artifact, and doing both
  // leaves nobody able to say what the ALLOW permitted.
  "execution": {
    "merchant":  "acme-procurement",
    "operation": "create_purchase_order",
    "payload":   { },
    "nonce":     "<caller-chosen, unique per action>"
  }
}

Response

{
  "decision":       "ALLOW" | "DENY" | "REQUIRE_APPROVAL" | "REPLAY",
  "reason_code":    "policy_allow",
  "policy_version": 3,
  "request_id":     "…",
  "audit_id":       "…",

  // Present only when the decision was ALLOW and an execution was requested.
  // Its absence is the statement that nothing was called — there is no empty
  // object and no null status a caller could read as a partial success.
  "execution": { "id": "…", "status": "SUCCEEDED" | "FAILED" | "UNKNOWN" }
}

Errors

Idempotency

`execution.nonce` binds one execution to one action. Repeating the same request with the same nonce returns the stored outcome as `decision: “REPLAY”` — no merchant call, no budget spent, no approval consumed, and no new decision.

Example

curl -sX POST https://gateway.example.com/v1/authorize \
  -H "authorization: Bearer $BENGAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "agent": "did:key:z6MkProcurement",
    "permit": "'"$PERMIT"'",
    "action": "purchase",
    "resource": "resource://company/procurement/laptop",
    "amount": { "minor": 500000, "currency": "TRY" }
  }'

import { Bengar } from "@bengar/sdk";

const bengar = new Bengar({ apiKey: process.env.BENGAR_API_KEY! });

const decision = await bengar.authorize({
  agent: "did:key:z6MkProcurement",
  permit,
  action: "purchase",
  resource: "resource://company/procurement/laptop",
  amount: { minor: 500_000, currency: "TRY" },
});

// Three values, and only one of them means go.
if (decision.decision !== "ALLOW") {
  // REQUIRE_APPROVAL is not an allow. Wait for the human.
  return;
}

List executions, newest first.

Auth: API key

Response

{ "executions": [ { "id", "status", "agent", "operation", "created_at" } ] }

Record what a person established about an UNKNOWN execution.

Auth: API key

Request

{ "execution_id": "…", "outcome": "SUCCEEDED" | "FAILED", "note": "what was checked" }

Errors

The active version and its document hash.

Auth: API key

Every version, with its state and who created it.

Auth: API key

Save a new version. Saving does not activate it.

Auth: API key · Roles: POLICY_AUTHOR

Request

{ "policy": { "spec_version": "…", "rules": [ … ] }, "note": "why" }

Errors

Ask what the policy would decide, without deciding anything.

Auth: API key · Roles: POLICY_AUTHOR, ADMIN, AUDITOR

Request

{
  "request": {
    "agent":    "did:key:z6Mk…",   // required — a simulation is about somebody
    "action":   "purchase",
    "resource": "resource://company/procurement/laptop",
    "amount":   { "minor": 500000, "currency": "TRY" }
  },
  "policy": { … }   // optional: simulate a candidate instead of the active one
}

Response

{ "policy_decision", "policy_reason", "policy_version", "matched_rules", "steps" }

Make a saved version the one that decides.

Auth: API key · Roles: POLICY_AUTHOR

Request

{ "version": 4 }

Approval requests and their status.

Auth: API key

Record an approval that was made elsewhere.

Auth: API key

Withdraw an approval that has not been consumed.

Auth: API key

Whether an agent is frozen, and since when.

Auth: API key

Stop an agent immediately.

Auth: API key

Let a frozen agent act again.

Auth: API key

The inclusion proof for one audit event.

Auth: API key

Response

{ "audit_event_id", "root", "leaf_version", "path": [ … ], "anchored_height" }

Verify an event and ask an independent witness about the root.

Auth: Console session · Roles: ADMIN, AUDITOR

Response

{
  "verification": "VERIFIED" | "INVALID" | "NOT_WITNESSED" | "UNAVAILABLE",
  "independently_witnessed": true,
  "reason": null,
  "evidence": { "local_proof", "chain_witness", "root", "anchored_height", "finality" }
}

Exchange a password for a session and a CSRF token.

Auth: None

Every project this person is a member of.

Auth: Console session

Mint an API key. The secret is returned once and never again.

Auth: Console session · Roles: ADMIN

Open an approval ceremony: returns the WebAuthn challenge and the Gateway's own reading of the obligation.

Auth: Console session · Roles: APPROVER

Finish the ceremony: verify the assertion and have Custody sign the approval.

Auth: Console session · Roles: APPROVER

The organization's chain signing address, or its absence.

Auth: Console session · Roles: ADMIN, AUDITOR

Provision the organization's signing key inside Bengar Custody.

Auth: Console session · Roles: ADMIN

What this organization has issued, from the read model.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR

One asset: supply, holders, transfers, supply history and gating.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR

Build one immutable intent and return the review projected from it. Nothing is signed and nothing reaches the chain.

Auth: Console session · Roles: ADMIN

What this organization authorized, and what the chain said.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR

Sign the stored intent in Custody and broadcast it.

Auth: Console session · Roles: ADMIN

Record what a person established about an UNKNOWN outcome.

Auth: Console session · Roles: ADMIN

The organization's own address, its balance and its recent native transfers.

Auth: Console session · Roles: ADMIN, AUDITOR

Build one immutable transfer intent and return the authorization decision. Nothing is signed.

Auth: Console session · Roles: ADMIN

Decide again, sign in Custody, and broadcast.

Auth: Console session · Roles: ADMIN

Chain identity, indexed height, chain head, lag and the read model's sync state.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

Validators this read model holds, with delegations seen and jailed status.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

One validator, with the delegations to it.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

Delegations by validator, beside native supply.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

Token-governance proposals, and the Bengar authority's configuration and members.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

One proposal, with the votes cast, the deposits and what executed.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER

The network treasury's completed payments, each with the proposal that authorised it.

Auth: Console session · Roles: ADMIN, AUDITOR, APPROVER, POLICY_AUTHOR, PERMIT_ISSUER