Human Gates

Pause sensitive API, SDK, and MCP actions for human approval before execution.

Human Gates

Human Gates let you pause selected execution requests until a person approves them. Use them when agents or customer workflows can send messages, change records, move files, spend money, or touch end-user-owned accounts.

They work across REST, SDKs, MCP Tool Mode, MCP Code Mode, Playground runs, and triggers.

When to use Human Gates

Good fits:

  • Review MCP tool calls before an agent posts externally
  • Require approval when an action uses an end-user scoped connection
  • Gate API or SDK execution for sensitive workspace integrations
  • Block or review actions that match recipients, domains, storage paths, or amount thresholds
  • Give operators an approval inbox without forcing your application to build one first
  • Send approval events to your own product so a reviewer can decide from your UI

How it works

  1. Create an approval policy in Approvals.
  2. Choose a template such as Review agent actions or Protect per-user credentials.
  3. Scope the policy to all workspaces or one workspace.
  4. Optionally narrow it to a configured integration alias and action.
  5. When execution matches the policy, Weavz returns approval_required instead of running the action.
  6. A reviewer approves or rejects the request in the Approvals inbox, your approval webhook, or a hosted approval link.
  7. The caller retries the same request with the same input and idempotency key.

Approval requests show a redacted input preview. Secret-looking values and enforced partial values are not exposed in the review UI.

Create a policy in the dashboard

  1. Open Approvals from the dashboard sidebar.
  2. Click New Policy.
  3. Pick a template.
  4. Choose a workspace scope.
  5. Select the execution sources to gate.
  6. Optionally select a configured integration and action.
  7. Choose approver roles and timeout.
  8. Save the policy.

Advanced matching lets you narrow by connection strategy, end-user presence, domain allowlists or denylists, and storage path prefixes.

Create a policy with the TypeScript SDK

typescript
import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { policy } = await client.approvalPolicies.create({
  name: 'Review MCP code actions',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  sources: ['mcp_code'],
  decision: 'require_approval',
  riskMode: 'always',
  approvers: [{ type: 'org_role', roles: ['owner', 'admin'] }],
  timeoutSeconds: 3600,
})

Handle approval_required

When an action needs approval, the API returns 202:

json
{
  "success": false,
  "status": "approval_required",
  "approval": {
    "id": "apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0",
    "status": "pending",
    "approvalAccessMode": "dashboard_and_hosted_link",
    "approvalUrl": "https://platform.weavz.io/approve/apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0?token=apr_link_v1_...",
    "hostedApprovalUrl": "https://platform.weavz.io/approve/apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0?token=apr_link_v1_...",
    "dashboardUrl": "https://dashboard.weavz.io/approvals/apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0",
    "expiresAt": "2026-05-14T12:00:00.000Z",
    "retry": {
      "idempotencyKey": "order-123-send-confirmation"
    }
  }
}

The caller should stop, surface the approval URL or approval ID, and retry after approval.

approvalAccessMode controls what URL is returned. Use dashboard_only when approvals must stay in the dashboard/API, dashboard_and_hosted_link when external MCP or SDK clients should receive a hosted bearer approval link plus dashboard context, and hosted_link_only when the customer wants to route only the hosted link through their own product.

For MCP Code Mode, one run can match several approval policies. Weavz groups predicted calls by policy and access mode. Hosted-link approvals can be completed from external clients, while dashboard-only approvals remain visible in the same response through the approvals array. After one approval is completed, retry with the returned approvalId; if another decision is still pending, Weavz returns that next approval instead of executing early.

typescript
const result = await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  integrationAlias: 'support_slack',
  input: { channel: 'C0123456789', text: 'Customer escalation is ready.' },
  idempotencyKey: 'ticket-421-escalation-message',
})
 
if ('status' in result && result.status === 'approval_required') {
  console.log('Needs approval:', result.approval.approvalUrl)
  await client.approvals.wait(result.approval.id)
 
  await client.actions.execute('slack', 'send_channel_message', {
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    integrationAlias: 'support_slack',
    input: { channel: 'C0123456789', text: 'Customer escalation is ready.' },
    idempotencyKey: result.approval.retry.idempotencyKey,
  })
}

Approve or reject programmatically

Use an API key with Human Gates decision permission. The same backend key can create and approve a request when that is the simplest product flow, as long as the key has access to the request's workspace or organization scope.

typescript
const backend = new WeavzClient({ apiKey: 'wvz_backend_key' })
 
await backend.approvals.approve('apr_9b36d3f761d84bb2b6f9a0c4b9d1f7e0', {
  reason: 'Customer-facing message reviewed.',
})

Send approvals to your product

Use a webhook approver when you want Weavz to create the gate but let your SaaS own the reviewer experience.

typescript
await client.approvalPolicies.create({
  name: 'Review high-impact sends',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  sources: ['sdk', 'mcp_tools', 'mcp_code'],
  integrationAliases: ['customer_mail', 'support_slack'],
  decision: 'require_approval',
  riskMode: 'always',
  approvers: [
    { type: 'webhook', webhookUrl: 'https://app.example.com/weavz/approvals' },
  ],
})

When the policy matches, your webhook receives an approval.requested event with:

  • approval.id
  • approval.status
  • approval.inputPreview
  • approval.redactedPaths
  • approval.hostedApprovalUrl
  • authenticated API decision endpoints in approval.api
  • Code Mode batch context in approval.codeRun, including codeRunId for grouping sibling approvals
  • retry context such as approval.idempotencyKey

The hosted approval URL is a short-lived reviewer link for that request. Treat it like a secret and show it only to the human reviewer. The URLs in approval.api are normal API endpoints, not bearer approval links; call them from your backend with an API key that has approvals.decide.

Weavz sends lifecycle events for approval.requested, approval.approved, approval.rejected, approval.canceled, and approval.expired. Webhook payloads include only the redacted preview, not raw action input or connection credentials.

MCP behavior

In MCP Tool Mode, a gated tool call returns an approval-required result with an authenticated dashboard approval URL. The agent should present that URL to the operator, wait for approval, then retry the same tool call with the same arguments.

In MCP Code Mode, Weavz treats the generated program as a batch approval. The first weavz_execute call stores the exact code and the MCP server tool surface, then returns an approval URL plus an approvalId. After the reviewer approves, the agent should call:

json
{ "approvalId": "apr_..." }

against weavz_execute instead of sending the code again. Weavz resumes the stored run once, caches the result for follow-up reads, and rejects the continuation if the MCP server tools changed after review. This avoids the loop where a prebuilt agent retries the original Code Mode run and creates a fresh approval request.

The dashboard approval view summarizes the Code Mode batch: likely tool calls, available app surface, external domains referenced by the code, storage/KV signals, and the exact code/tool-surface hashes. This summary is deterministic and redacted; it is reviewer context, not a replacement for your policy rules.

For per-user integrations, use MCP OAuth so each user approves and runs with their own connected accounts.

Next steps

  • Open Approvals in the dashboard — review pending requests and manage template-based policies
  • Approvals API Reference — endpoints for policies, approval inbox, and decisions
  • API Keys — create scoped keys and enable Human Gates decisions when a backend should approve or reject gated work
  • Executing Actions — action execution and idempotency
  • MCP Code Mode — expose broad agent workflows through Code Mode
  • Input Partials — enforce hidden defaults before approval review