Action Control
Action Control API reference
REST operations, MCP tools, scopes, webhook events and error codes for Action Control.
Every Action Control operation is a REST endpoint under /v1 and an MCP tool on the Audon MCP server, with the same scopes. This is the API formerly called the Action Integrity API: the rename didn’t change any endpoint, operation id (integrity.*), scope or MCP tool name. Conventions (authentication, errors, pagination, rate limits) are on the REST API page; the full schema is the OpenAPI 3.1 specification. This list is generated from the operation registry: 71 operations.
Scopes
integrity:execute: agent keys only. No role holds it, so people, admin API keys and OAuth grants can never execute an action.integrity:actions:read: every role.integrity:approvals:decide: owner and admin, signed-in people only.integrity:agents:write,integrity:connectors:write,integrity:policies:write: owner and admin.integrity:audit:write: owner, admin and analyst.
Operations
Execute (agent keys)
| Endpoint | Description |
|---|---|
POST /v1/integrity/actionsMCP integrity_execute · integrity:execute | Propose a business action (refund, credit, discount, subscription change, order cancel). Audon checks identity, permission, business rules, limits, duplicates and approvals, executes it through the connector only if allowed, verifies the outcome and records evidence. Agent keys only. Idempotent per key: a retry with the same key returns the original result. Decision (allowed, denied, pending_approval, would_deny) and outcome (executing, completed, failed, unknown, not_executed, awaiting_approval) are separate fields; never retry an unknown outcome with a new key. Field names: action_type, amount_minor (integer minor units), idempotency_key; the SDK’s names (action, amount, idempotencyKey, connectorId) are accepted as aliases. Test ids (ch_test_refundable, cus_test_customer, sub_test_active, order_test_1001) run through the Test connector: simulated, no money moves. Before protection is on for a real connector, the action is denied with decision_code no_connector and turn_on_protection_url. |
GET /v1/integrity/actions/{action_id}/statusMCP integrity_action_status · integrity:execute | An agent reads the current decision and outcome of one of its own actions, by action id. Agent keys only; other agents’ actions are not found. |
POST /v1/integrity/actions/{action_id}/retryMCP integrity_action_retry · integrity:execute | Retry one of your own failed actions when the provider has proven it did not happen (retry_safe: true). Re-checks business rules and duplicates, then sends a new attempt with a new provider idempotency key. Unknown outcomes can’t be retried until reconciliation resolves them. Agent keys only. |
Actions, activity and approvals
| Endpoint | Description |
|---|---|
GET /v1/integrity/overviewMCP integrity_overview_get · integrity:actions:read | KPIs for a period: protected actions, verified successful, blocked, pending approvals, confirmed prevented loss and potentially prevented loss (separate, never summed; one intent counted once), unknown exposure and investigations, plus per agent, per action type and per UTC day (allowed, sent for approval, blocked). |
GET /v1/integrity/activityMCP integrity_activity_list · integrity:actions:read | The live feed of agent actions, newest first: headline ("Refund blocked"), agent, amount, reason, decision, outcome and evidence class. Filters: agent_id, decision, outcome, action_type, evidence_class, resource, since, until (comma-separated values allowed). Cursor pagination. |
GET /v1/integrity/actionsMCP integrity_actions_list · integrity:actions:read | List actions with the same filters as the activity feed (for tables and exports). Cursor pagination, newest first. |
GET /v1/integrity/actions/{action_id}MCP integrity_action_get · integrity:actions:read | One action with everything behind its decision: agent identity, every check with its reason, the policy versions and matched rules, provider transaction data, approval, the verified outcome, the outcome timeline and the hash-chained evidence (with a chain check). |
GET /v1/integrity/approvalsMCP integrity_approvals_list · integrity:actions:read | Approvals waiting for a person (status=pending, the default) or decided ones (approved, denied, expired, or all), with the action, the agent, the amount and the time left. |
POST /v1/integrity/approvals/{approval_id}/decideMCP integrity_approval_decide · integrity:approvals:decide | Approve or deny an action waiting for a person, with a reason. Approved actions are re-checked against fresh provider state and executed exactly once; denied ones are recorded as blocked. Signed-in people with the approval’s role only: agents and API keys get forbidden. |
POST /v1/integrity/actions/{action_id}/reconcileMCP integrity_action_reconcile · integrity:agents:write | Look up an action whose outcome is unknown (or pending) at the provider now, instead of waiting for the reconcile job. Resolves to completed or failed only on a conclusive provider answer; never re-sends the action. |
POST /v1/integrity/actions/{action_id}/confirm-preventedMCP integrity_action_confirm_prevented · integrity:approvals:decide | A reviewer confirms that a blocked action would have executed and caused loss (with a reason). The amount moves from potentially prevented to confirmed prevented, marked reviewer-confirmed with who confirmed it. Signed-in people only. |
GET /v1/integrity/action-typesMCP integrity_action_types_list · integrity:actions:read | Every action type agents of this organization can be allowed: the built-in ones (executed by Stripe, Shopify, a Webhook or the Test connector, with built-in business rules) and your own (from the catalog or custom; executed by a chosen Webhook connector or decision only). Each with category, risk, fields (amount, count, resource, typed attributes), execution, version, whether it can run now (executable: live, test_only, needs_connector, needs_protection, decision_only, archived) and how many agents may run it. |
GET /v1/integrity/action-types/{action_type}MCP integrity_action_type_get · integrity:actions:read | One action type by id (e.g. email.send): its definition, every version (semantic changes are versioned; actions record the version they ran under) and whether it can run now. |
POST /v1/integrity/action-typesMCP integrity_action_type_create · integrity:policies:write | Define your own action type (org-scoped): id (dot-namespaced, e.g. loyalty.points.grant), name, description, category (a catalog category or your own with category_name), risk, fields (amount yes/no with an optional fixed currency, count with what it counts, the resource label, typed attributes policies can test as params.<key>) and execution: "webhook" (your Webhook connector executes it: signed request, idempotency key, status endpoint for reconciliation) or "decision_only" (Audon decides allow/deny/approval and records evidence; your agent executes it and reports the outcome, recorded as agent-reported). Policies, approvals, limits, duplicates, pause and evidence apply exactly as for built-in actions. No agent may run it until it is in that agent’s allowed actions. |
POST /v1/integrity/action-types/from-templateMCP integrity_action_types_add_template · integrity:policies:write | Add one or more catalog templates (template_ids, e.g. ["email.send","crm.contact.delete"]) to your organization as action types (editable copies). execution: "decision_only" (default) or "webhook" with connector_id. with_policy: also create a draft policy with the templates’ suggested rules (drafts never apply; a person activates them). Already added templates are returned unchanged; built-in ones need no adding. |
PATCH /v1/integrity/action-types/{action_type}MCP integrity_action_type_update · integrity:policies:write | Change one of your action types. Name and description change in place; fields, execution, connector, risk or category create a new version (kept; actions record the version they ran under). A semantic change to a type that an agent may run needs a signed-in person (it can loosen the controls); API keys can rename and change types no agent uses yet. |
POST /v1/integrity/action-types/{action_type}/archiveMCP integrity_action_type_archive · integrity:policies:write | Stop an action type: every action of this type is denied (action_type_archived) until a person restores it. Its versions and the actions that ran under it stay. API keys may archive (it only tightens). |
POST /v1/integrity/action-types/{action_type}/restoreMCP integrity_action_type_restore · integrity:policies:write | Restore an archived action type, so agents allowed to run it can again. Signed-in people only (it loosens the controls). |
POST /v1/integrity/actions/{action_id}/outcomeMCP integrity_action_report_outcome · integrity:execute | Decision-only actions: after Audon allowed one of your actions (outcome awaiting_report), you executed it yourself; report what happened: status completed or failed, the id in your system (external_id) and a short message. Recorded as agent-reported evidence, weaker than a provider-verified outcome. Agent keys only, own actions only, once per action. |
Agents
| Endpoint | Description |
|---|---|
GET /v1/agentsMCP agents_list · integrity:actions:read | Agents of the organization (platform objects, agt_): identity, owner, environment, status (active or paused), allowed actions, mode, cost attribution, their action counts over the last 30 days and last_seen_at (the newest call with one of its keys or action; null = not connected yet). |
GET /v1/agents/{agent_id}MCP agent_get · integrity:actions:read | One agent with its keys (prefixes only), the policies whose rules name it, and its last 30 days of actions by decision and outcome. |
POST /v1/agentsMCP agent_create · integrity:agents:write | Register an agent: name, owner, environment, the action types it may propose (allowed_actions), mode (inherit the organization’s monitoring/enforcing, or monitor/enforce for this agent) and optionally where its model spend is billed (cost_attribution: provider project, workspace or API key ids). |
PATCH /v1/agents/{agent_id}MCP agent_update · integrity:agents:write | Change an agent’s name, owner, environment, allowed actions, mode or cost attribution. Switching an agent to enforce makes its policy denials block; monitor only records them as "Would deny" (built-in safety checks block in both). Widening allowed actions or changing the mode needs a signed-in person; API keys can narrow allowed actions. |
POST /v1/agents/{agent_id}/pauseMCP agent_pause · integrity:agents:write | Kill switch: every action this agent proposes is denied (and recorded) until a person resumes it, in monitoring and enforcing mode alike. Pending approvals for it will not execute. |
POST /v1/agents/{agent_id}/resumeMCP agent_resume · integrity:agents:write | Resume a paused agent. Signed-in people only: a paused agent can’t be resumed by an agent or API key. |
GET /v1/agents/{agent_id}/keysMCP agent_keys_list · integrity:actions:read | An agent’s keys (prefix, last use, expiry). Secrets are never returned after creation. |
POST /v1/agents/{agent_id}/keysMCP agent_key_create · integrity:agents:write | Create a key bound to this agent (aa_agent_…). It carries only integrity:execute: it can propose this agent’s allowed actions and read their status, nothing else. The secret is shown once. Signed-in people only. |
POST /v1/agents/{agent_id}/test-actionMCP agent_send_test_action · integrity:agents:write | Send one test action as this agent through the full pipeline (identity, permission, business rules, your policies, duplicates, evidence) against the Test connector: simulated, nothing reaches a provider, no money moves, never billed or counted in KPIs. Shows that the agent and your policies work before anything is live. Uses the first allowed action type (refund.create first) unless action_type is given. Signed-in people only. |
DELETE /v1/agents/{agent_id}/keys/{key_id}MCP agent_key_revoke · integrity:agents:write | Revoke an agent key immediately. |
GET /v1/agents/{agent_id}/costMCP agent_cost_get · spend:read | The agent’s model spend from Spend Optimization billing data, by the provider projects, workspaces and API keys in its cost attribution: per currency (micros, never converted) and per day, next to its action count for the same period. Without attribution it says so instead of showing 0. |
POST /v1/agents/enrollment-keysMCP agent_enrollment_key_create · integrity:agents:write | Create an enrollment key (aa_enroll_…) so agents can register themselves on the Action Gateway (register_agent). It can register agents and nothing else. Set what self-registered agents get: default_actions (default none), requires_approval (default true: a new agent can do nothing real until a person approves it), allow_test_actions (default true: before approval it may try its requested actions with test ids, simulated), environment, max_agents and expiry. Anything an agent asks for beyond the defaults becomes an access request a person decides. The secret is shown once. Signed-in people only. |
GET /v1/agents/enrollment-keysMCP agent_enrollment_keys_list · integrity:actions:read | Enrollment keys with their defaults for self-registered agents, how many agents registered with each and their state. Secrets are never returned. |
DELETE /v1/agents/enrollment-keys/{key_id}MCP agent_enrollment_key_revoke · integrity:agents:write | Revoke an enrollment key at once: registrations with it fail. Agents that already registered keep their own agent keys. |
POST /v1/agents/registerMCP agent_register · integrity:agents:register | An agent registers itself with an enrollment key (aa_enroll_…): name, purpose, environment and the actions it needs (requested_actions, each with an optional limit: max_amount_minor + currency, or max_count). Creates the agent and returns its own agent key (aa_agent_…, shown once) and its status. It gets only the enrollment key’s default actions; everything else becomes an access request a person approves under Approvals. Until then it may try its requested actions with test ids (simulated) if the key allows it. Enrollment keys only; rate-limited and recorded in the activity log. |
GET /v1/agents/meMCP agent_self_status · integrity:execute | An agent reads its own status: active, pending (waiting for a person to approve it) or paused; the actions it may run, each with whether it runs now (live, test ids only, decision only, needs a connector); actions it may only test; its access requests and their state; and when Audon last saw it. Agent keys only. |
POST /v1/agents/me/access-requestsMCP agent_request_actions · integrity:execute | An agent asks a person for more actions (each with an optional limit: max_amount_minor + currency, or max_count) and says why. Creates an access request shown under Approvals ("Support bot requests refund.create up to $200.00"); a signed-in person approves or denies it. Grants nothing by itself. Agent keys only. |
POST /v1/agents/me/test-actionMCP agent_self_send_test_action · integrity:execute | An agent sends one of its allowed (or test-only) actions with a test id through the full pipeline: identity, permission, your policies, duplicates and evidence; executed by the Test connector (simulated, no money moves, never billed). Decision-only actions come back awaiting_report. Agent keys only. |
GET /v1/agents/me/catalogMCP agent_self_catalog · integrity:execute | For an agent: the action ids it could ask for with request_actions, by category (built-in, the organization’s own action types and catalog templates), with risk and whether it carries an amount or a count. Agent keys only. |
GET /v1/agents/access-requestsMCP agent_access_requests_list · integrity:actions:read | Requests from agents for actions (at self-registration or later), newest first: who asks, for what and why ("Support bot requests refund.create up to $200.00"). status: pending (default), approved, denied or all. |
POST /v1/agents/access-requests/{request_id}/decideMCP agent_access_request_decide · integrity:agents:write | A signed-in person approves (all or some of the requested actions: approve_actions) or denies an agent’s access request, with a reason. Approving adds the actions to the agent (catalog templates are added to the organization first, decision only), activates a pending self-registered agent, and turns requested limits into an active policy for that agent. Denying a registration pauses the agent. Agents, enrollment keys and API keys can’t decide; an agent never approves its own request. |
Connectors
| Endpoint | Description |
|---|---|
GET /v1/integrity/connectorsMCP integrity_connectors_list · integrity:actions:read | Business-system connectors (Stripe, Shopify, Webhook): how each is connected (one-click OAuth or key), mode (read-only or execute), access (can_execute, read_only, needs_attention), health, verified permissions and the actions each can run. Secrets and tokens are never returned. |
GET /v1/integrity/connectors/{connector_id}MCP integrity_connector_get · integrity:actions:read | One connector with health, permissions and its last-30-day action counts. |
POST /v1/integrity/connectorsMCP integrity_connector_create · integrity:connectors:write | Connect with a key: Stripe with a restricted key rk_… (the fallback to the one-click Stripe connection, integrity_connector_oauth_start; read-only for the free action audit, execute mode needs write permissions for the actions you protect) or a Webhook connector (your endpoint executes actions; Audon signs requests and needs a status endpoint for reconciliation). Secrets are encrypted and never returned. Execute mode can only be set by a signed-in person. |
PATCH /v1/integrity/connectors/{connector_id}MCP integrity_connector_update · integrity:connectors:write | Rename a connector, switch read-only/execute (execute: signed-in people only), replace its Stripe key, change Webhook URLs or timeout, or enable/disable it. Re-checks health. |
POST /v1/integrity/connectors/{connector_id}/testMCP integrity_connector_test · integrity:connectors:write | Check the connector now: Stripe reads and permission probes (no side effects), Webhook ping. Updates health and permissions. |
DELETE /v1/integrity/connectors/{connector_id}MCP integrity_connector_delete · integrity:connectors:write | Disconnect: the credential (key or OAuth tokens) is destroyed and the connector is disabled (its actions and evidence stay). Revoke the key, or uninstall the Audon app in Stripe or Shopify, too. |
GET /v1/integrity/connectors/oauthMCP integrity_connector_oauth_options · integrity:actions:read | Which official one-click connections are available (the one Audon Stripe App, the Shopify app), the permissions each requests at install (read and write, one install for the audit and execution; Audon only reads until a person turns on protection), the redirect URIs to register and, for each action type, the provider permissions it needs. No secrets. |
POST /v1/integrity/connectors/oauth/startMCP integrity_connector_oauth_start · integrity:connectors:write | Human-only. Starts the official connection: returns the provider URL (Stripe App install link, or the Shopify store’s consent page) with a one-time state valid for 10 minutes. One install requests read and write access for every action; purpose only sets the connector’s mode in Audon: "audit" (default) connects read-only, so Audon only reads until a person turns on protection (integrity_connector_update mode "execute", no second install); "execute" connects with protection on. Pass connector_id to reconnect or upgrade an existing connector (one installed with the earlier read-only Stripe app). Shopify needs the store’s myshopify.com domain. |
POST /v1/integrity/connectors/oauth/completeMCP integrity_connector_oauth_complete · integrity:connectors:write | Human-only. Completes the connection from the provider’s callback: checks the one-time state (same person and organization), for Shopify the HMAC and the shop domain, exchanges the code, stores the tokens encrypted and checks the granted permissions. Called by the web callback; agents never need it. |
GET /v1/integrity/connectors/connect-linkMCP integrity_connector_connect_link · integrity:actions:read | The one-click Stripe and Shopify connections are consent screens a person opens in their browser. This returns the page to send them (human_url), what they do there, and the operation to poll until the connector exists (poll_with: integrity_connectors_list). An agent can create a Webhook connector itself (integrity_connector_create). |
Policies
| Endpoint | Description |
|---|---|
GET /v1/integrity/policiesMCP integrity_policies_list · integrity:actions:read | Policies with their status and active version, and the active rules in plain words. |
GET /v1/integrity/policies/{policy_id}MCP integrity_policy_get · integrity:actions:read | One policy with every version: rules, plain-words summary, natural-language source, validation, replay and who confirmed it. |
POST /v1/integrity/policiesMCP integrity_policy_create · integrity:policies:write | Create a policy with a first draft version of rules (validated against the schema and your agents). Drafts never apply: a person activates a version after reviewing its replay. |
POST /v1/integrity/policies/{policy_id}/versionsMCP integrity_policy_create_version · integrity:policies:write | Add a new draft version with changed rules. Active versions never change; a new version becomes active only when a person activates it. |
POST /v1/integrity/policies/validateMCP integrity_policy_validate · integrity:actions:read | Check a rule set against the schema and your agents without saving it. Returns errors, warnings and the rules in plain words. |
POST /v1/integrity/policies/replayMCP integrity_policy_replay · integrity:actions:read | What a rule set (draft rules, or a policy version) would have done over the last N days of stored actions and audited history: allowed, denied and sent to approval, how many decisions change, per-rule matches, and warnings ("always allows", "never matches"). Read-only. |
POST /v1/integrity/policies/draftMCP integrity_policy_draft · integrity:policies:write | Policy builder: turn a plain-language description ("refunds up to $100 autonomously, above needs a manager") into structured rules, validate them and replay them against the last 30 days. Uses an LLM when the platform has one configured, otherwise a deterministic phrase parser. Nothing applies until a person activates a version; save_to creates a draft version. |
POST /v1/integrity/policies/{policy_id}/versions/{version}/activateMCP integrity_policy_activate · integrity:policies:write | A person confirms a version: it is re-validated, replayed against the last 30 days and becomes the active version (the previous one is superseded). The activation, the natural-language source, the rules, the validation and the confirmer are recorded. Signed-in people only; confirm must be true. |
POST /v1/integrity/policies/{policy_id}/archiveMCP integrity_policy_archive · integrity:policies:write | Stop applying a policy (its versions stay for the evidence that references them). Archiving an active policy needs a signed-in person. |
Action audit
| Endpoint | Description |
|---|---|
POST /v1/integrity/auditsMCP integrity_audit_start · integrity:audit:write | Free, read-only historical audit: imports refunds, payments, customer credits, coupons and canceled subscriptions from a Stripe connector, or orders, refunds, discount codes, gift cards and store credit from a Shopify connector (up to 90 days) plus any uploaded agent logs, and looks for duplicate refunds, refunds above the payment, unusual discounts and credits, bursts, failed and repeated actions, and refunds without a matching agent call. Runs in the background; poll integrity_audit_get. |
POST /v1/integrity/audit-logsMCP integrity_audit_upload_logs · integrity:audit:write | Upload agent tool-call logs for the action audit: JSONL (one object per line with timestamp, agent, tool, arguments, result/status) or an OpenTelemetry JSON export with GenAI tool spans (gen_ai.tool.name, gen_ai.tool.call.arguments). Business tool calls (refund, credit, discount, subscription, order cancel) are mapped to actions; the file itself and everything else (arguments are kept only as a hash, no messages) is not stored. The stored rows are deleted automatically the organization’s retention period after the audit (7, 30 or 90 days; default 30); the findings stay. Over REST send the file as the body with Content-Type application/x-ndjson or application/json. |
GET /v1/integrity/auditsMCP integrity_audits_list · integrity:actions:read | Action audits, newest first, with status, coverage and finding counts. |
DELETE /v1/integrity/audit-logs/{upload_id}MCP integrity_audit_log_upload_delete · integrity:audit:write | Delete the stored records of one agent-log upload now, instead of waiting for automatic retention. Findings already derived from them stay. Cannot be undone. |
GET /v1/integrity/audits/{audit_id}MCP integrity_audit_get · integrity:actions:read | One action audit: status, coverage (what was imported, truncation) and totals by evidence class (flagged, suspected loss, confirmed loss; historical losses are never "prevented"). |
GET /v1/integrity/audit-findingsMCP integrity_audit_findings_list · integrity:actions:read | Findings of the action audit with their evidence class (flagged_action, suspected_loss, confirmed_loss), amount, severity and evidence; totals per class and currency kept apart. Filters: status, classification, detector. |
POST /v1/integrity/audit-findings/{finding_id}/reviewMCP integrity_audit_finding_review · integrity:audit:write | Acknowledge, dismiss (with reason) or confirm a finding. Confirming a suspected loss makes it a reviewer-confirmed confirmed_loss and needs a signed-in person. |
Activation and gateway
| Endpoint | Description |
|---|---|
GET /v1/integrity/activationMCP integrity_activation_get · integrity:actions:read | Where this organization is with Action Control: not_started → audit_connected → audit_ready → monitoring (built-in safety checks block; the customer’s own policies run in shadow: "Would deny") → enforcing, with what exists (connectors, agents, policies) and the next step. |
POST /v1/integrity/activationMCP integrity_activation_set_mode · integrity:policies:write | Switch the organization between monitoring (the customer’s own policies in shadow: recorded as "Would deny" / "Would need approval", not blocking) and enforcing (policies block, approvals hold). Built-in safety checks (identity, paused agent, allowed actions, business rules, duplicates, Unknown state) block in both modes. Agents set to monitor or enforce keep their own mode. Signed-in people only. |
GET /v1/integrity/gatewayMCP integrity_gateway_get · integrity:actions:read | How agents reach Action Control: the Action Gateway MCP endpoint and its tools (one per action type; `live` says whether a connector with protection on can run it), the REST endpoint, a ready SDK snippet, the field names (canonical and accepted aliases) and the test ids the Test connector accepts. |
Webhook events
integrity.action.decidedintegrity.action.completedintegrity.action.failedintegrity.action.unknownintegrity.approval.requestedintegrity.approval.decidedintegrity.policy.activatedintegrity.audit.completed
Admin changes go to the activity log; agent actions are recorded as evidence, cross-linked by action id.
Error codes
| Code | Meaning |
|---|---|
idempotency_conflict | The idempotency key was used for a different action. Use a new key for a new intent. |
entitlement_required | The free plan’s protected actions for the month are used up. Nothing was executed. |
insufficient_scope | The credential lacks the scope; only agent keys hold integrity:execute. |
validation_failed | The input doesn’t match the action type’s parameter schema. |
conflict | Another person decided the approval first. |
rate_limited | Too many requests; retry after Retry-After with the same idempotency key. |
A denied action is not an error: it is a normal result with decision: "denied", a decision_code and a decision_reason.
Last updated