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 policy 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.

---

Push notifications

When an approval is requested or decided, the people involved get a push notification (when they have registered a device). The notification payload carries:

Field	Description
tenant_id	Company the notification belongs to — tapping it opens the chat directly in the right company
tenant_name	Company name, for display (may be absent)
category	approval_pending for a request awaiting the approver; approval_outcome for the result sent to the requester
pending_action_id	(approval_pending only) Id of the pending approval

• An approval_pending notification opens the approvals inbox. You cannot approve or decline from the push itself — the decision is only made in the interface.
• An approval_outcome notification opens the requester's conversation, where the receipt is.
• A notification is only delivered to people who are still active members of the company. If membership cannot be verified, nothing is sent.
• A device receives notifications from all the companies of its owner, not only from the ones opened on that device. Registering a device that was previously registered by another person removes it from the previous person's account.

---

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. An unknown value returns 400 listing the accepted values

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.