Agent authority API

Human authentication

POST /auth/login with email and password. The server issues an HttpOnly session cookie lasting 12 hours. All human POST requests require the exact application Origin and Content-Type: application/json. Accounts are provisioned by the operator.

• GET /v1/state — organization, agents, policies, delegations, requests and catalog.
• POST /auth/logout — invalidate the session.

Configure authority

These operations require an owner session.

• POST /v1/agents — register name and base64url Ed25519 public_key.
• POST /v1/policies — create an immutable policy with currency, suppliers, per_action_minor and approval_above_minor.
• POST /v1/delegations — grant an agent a policy, budget_minor and expires_at in Unix seconds.
• POST /v1/delegations/{id}/revoke — withdraw authority and cancel unexecuted requests.

Each delegation has a separate lifetime budget. Amounts are integer USD cents. Policies are immutable: issue a new delegation to apply a new policy.

Signed agent requests

POST /v1/authorizations with a signed envelope containing payload and signature. The payload is unpadded base64url of exact UTF-8 intent JSON. Sign the bytes prefixed with trellis-intent-v1 and a newline, using Ed25519.

The intent contains org_id, agent_id, delegation_id, action=purchase.create, audience=trellis-procurement-v1, nonce, expires_at, supplier_id, item_id, quantity, amount_minor and currency. Expiry is at most 15 minutes away and no later than the delegation.

A 201 response returns authorized, awaiting_approval or denied. Authorized and approval-pending requests reserve budget atomically.

To execute, POST /v1/executions with a new signed intent using action=purchase.execute, a fresh nonce, authorization_id and intent_digest. The original stored purchase is executed. Returns 202/pending; inspect workspace state for the final simulated outcome.

Human approval

POST /v1/approvals/{authorization_id}/decision with decision=approve or reject and the exact intent_digest. Requires an owner or approver session. An agent signature cannot approve an action.

Retry semantics

Resend the exact same envelope after a network failure. A nonce identifies one operation per organization and agent. Identical bytes return the original response; changed bytes return 409. A fresh execution attempt cannot consume the same authorization twice. Read workspace state to see transitions after the original response.

Audit evidence

GET /v1/evidence exports the complete organization event chain and signed checkpoint. GET /v1/trust-root returns the current evidence key. Both require a human session.

Events sign exact bytes with prefix trellis-event-v1 and newline; checkpoints use trellis-checkpoint-v1 and newline. Verify against a public key obtained through an independently trusted channel. Retain checkpoints separately to detect rollback. Signatures do not establish legal identity, runtime attestation or settlement.

Reconciliation

POST /v1/reconciliation/import accepts {events: [...]} with up to 100 simulated provider events. Owner access required. Each event has event_id, reference, revision, status, amount_minor, fee_minor, currency, supplier_id and occurred_at (Unix seconds). Revisions form a contiguous sequence starting at 1 per payment. Supported statuses: pending, settled, failed, returned.

Exact duplicate imports are skipped. Reused IDs with different facts are retained and flagged. This manual feed is a simulation, not a verified provider webhook.

• POST /v1/reconciliation/runs — save an immutable comparison snapshot (owner or approver).
• GET /v1/reconciliation — latest 20 runs and 100 review notes.
• POST /v1/reconciliation/reviews — add run_id, item_key and note. Notes never clear discrepancies.
• GET /v1/reconciliation/example-feed — download synthetic facts generated from internal orders for testing.

Matching requires an exact reference, amount, currency, supplier and consistent event history. Missing evidence remains unresolved. Returned payments stay distinct from failed payments. Fees are reported but not validated against a pricing agreement. Reconciliation never changes budgets or execution status.

Developer API keys & limits

The Developer API tab lets owners create scoped, expiring keys and review usage. POST /v1/developer-keys returns a secret once; GET /v1/developer-keys lists metadata; POST /v1/developer-keys/{id}/revoke revokes it; GET /v1/developer-usage shows current counters.

Machine authorization and execution require Authorization: Bearer <key> plus the agent-signed envelope. Keys never substitute for signatures or payment authority. Defaults: 30 requests/minute and 1,000/day per key; shared organization ceiling 60/minute and 5,000/day. Service-wide ceilings also apply. UTC windows and counters persist across restarts. HTTP 429 includes Retry-After. Retries and denied evaluations consume admitted request slots.

The protobuf service defines the generated JSON routes. JSON keeps numeric amounts and snake_case names. The request server and simulator worker now run as separate processes. The linked OpenAPI document is generated from the protobuf descriptors.