Agent policies

An agent policy controls what the MCP server is allowed to do on behalf of your workspace. Policies live at the organization + environment level. Every agent session in the same workspace sees the same rules, so new sessions don't have to be re-authorized.

If no policy exists, defaults are conservative: only read-only tools are allowed, and every write requires approval.

Fields

allowed_tools is enforced before approval handling. A tool that is not in the list returns 403 tool … not allowed by policy.

Dashboard grouping

The dashboard policy dialog groups tools by resource family: Payment Orders, Addresses, Webhooks, Checkout Sessions, Agents, and Merchant Subscriptions. You can select or clear an entire group, or choose individual tools. Quick presets cover read-only defaults, payment collection, subscription management, select all, and clear all.

Read the current policy

curl -X GET https://api.stableops.dev/v1/agent/policy \
  -H "authorization: Bearer $STABLEOPS_API_KEY"

The environment (sandbox or live) is determined by the API key itself (sk_sandbox_… vs sk_live_…); there is no environment header to send.

{
  "id": "agp_01",
  "allowed_tools": ["get_order", "list_webhook_deliveries"],
  "require_approval": true,
  "created_at": "2026-07-01T08:00:00.000Z",
  "updated_at": "2026-07-01T08:00:00.000Z"
}

Update the policy

POST /v1/agent/policy performs an upsert. Omitting require_approval keeps its current value, but omitting allowed_tools resets the whitelist to the read-only default set — always send the full tool list you want to keep.

curl -X POST https://api.stableops.dev/v1/agent/policy \
  -H "authorization: Bearer $STABLEOPS_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "allowed_tools": [
      "get_order",
      "create_payment_order",
      "request_action_approval"
    ],
    "require_approval": false
  }'

Decision flow

tool call ─▶ /v1/agent/actions
              │
              ├─ tool in allowed_tools?            no ─▶ 403 not allowed
              │
              ├─ read-only tool?                   yes ─▶ auto_allowed
              │
              └─ require_approval == true?         yes ─▶ pending_approval (queue for human)
                                                   no  ─▶ auto_allowed (agent proceeds)

The dashboard surfaces every pending_approval action, the requested arguments, and the agent session that asked for it. Approving an action unblocks the tool call on the next retry; rejecting it records the operator's reason in the audit log.

Recommended profiles

Strict: fully manual review, useful for the first live integration:

{
  "allowed_tools": ["get_order", "list_webhook_deliveries"],
  "require_approval": true
}

Payment automation: let the agent open payment orders without approval after you explicitly allow the payment tools:

{
  "allowed_tools": [
    "get_order",
    "create_payment_order",
    "request_action_approval"
  ],
  "require_approval": false
}

Audit-only: keep approvals on but let read tools fan out widely:

{
  "allowed_tools": ["get_order", "list_webhook_deliveries"],
  "require_approval": true
}

Tips

• Start in sandbox with require_approval=true, then disable approvals only for tool groups you are ready to automate.
• Revoking an agent session is separate from the policy: it blocks one conversation; updating the policy blocks every session.
• Approvals are stamped with the operator's id (the dashboard user or the approver_id you send to /v1/agent/actions/:id/approve). The audit trail is queryable per session.