Action Approvals

Action approvals let you require a human to sign off before an agent runs a sensitive action. Unlike a static per-tool flag, approvals are a governance rule: which actions need approval is configured in the Contextual Security Policy (CSP), and who approves is defined by an approval policy. The approver can be a different user — for example, a manager approving an action requested by a team member.

Native chat only

Action approvals apply only in the native chat (chat.zihin.ai). The agent mediates the whole flow inside the conversation.

---

How it works

1. A user chats with an agent and asks for something that triggers a sensitive action (a tool that matches an approval scope).
2. Instead of running the tool, the agent pauses and delivers an approval card to the approver's own chat session (with a push notification).
3. The approver — who may be a different user, such as a manager — approves or declines in their chat.
4. On approval, the action runs outside the agent loop, with its arguments frozen at the moment it was proposed.
5. The result flows back to the original requester as a receipt (with a push notification).

The action never runs before approval. If it's declined, it doesn't run at all.

---

Configuration

Approvals are configured in two places, both covered in detail on the Security Policies page:

1. The trigger — require_approval_for in the CSP behavior policy declares which tools need approval, and approval_policy_id points to the policy that decides who approves.
2. The approval policy — an approval_policies record that names the approvers (specific users, or everyone with a given role).

A minimal example of the trigger, in a behavior policy:

{
  "policy_type": "behavior",
  "rules": {
    "behavior": {
      "require_approval_for": [
        "create_deal",
        { "mcp_server_id": "erp-protheus" }
      ],
      "approval_policy_id": "b1a2c3d4-..."
    }
  }
}

See Security Policies → Action Approvals for the full schema, matching rules, and policy structure.

---

Safe by default

• A policy with no valid approver blocks the action with a clear message — it never creates a card that nobody can resolve.
• Sensitive argument keys are redacted in the approval card.
• The pending-approvals list is scoped by role: a regular member sees only their own requests; admin and owner see all.
• Decisions are atomic — the first decision wins.

---

Endpoints

GET /api/v1/approvals

List pending approvals (a kanban-style view). Requires the sessions:approve-action permission. The result is scoped by role: a member sees only requests they are involved in; admin/owner see all.

Query Parameters:

Param	Type	Description
status	string	Filter by status: awaiting_user (default), approved, rejected, expired, or all

Approval policies

CRUD for the policies that decide who approves.

Endpoint	Method	Permission	Description
GET /api/v1/approval-policies	GET	csp:read	List approval policies
POST /api/v1/approval-policies	POST	csp:create	Create a policy
PUT /api/v1/approval-policies/:id	PUT	csp:update	Update a policy

---

Related

• Security Policies → Action Approvals — full configuration reference.
• Skills — the destructive_action_guard skill is a lighter, prompt-level alternative when you want the agent to ask the same user to confirm, rather than route to a separate approver.