Approval lifecycle

Set a review boundary

A HOLD rule creates a checkpoint on a supported integration. Review the action, target, policy, masked context, expiry, and timeout outcome before approving. Approval authority belongs to an authorized workspace member, not merely to the holder of an application API key.

Review an action before resolving it

1. Confirm the workspace and environment, then identify the exact action and target.
2. Read the matched policy and the context available to the reviewer. Identify any missing information needed for the decision.
3. Check the requester’s identity, your approval authority, and any applicable separation-of-duties restriction.
4. Check the expiry and timeout outcome. Resolve the checkpoint only if it is still actionable and you can assess the request.
5. Confirm the recorded resolution and the integration’s resulting behavior. Use a new checkpoint for a materially different action.

For team rollout, assign backup approvers and an escalation path. Test both notification delivery and actual resolution with harmless actions. Operational responsibilities.

States and outcomes

State	Interpretation
pending	Awaiting resolution; no final permission yet
approved	Human approval, subject to the integration’s resume contract
denied	Human denial
expired	Apply the configured timeout outcome
abandoned / cancelled	The caller or lifecycle stopped the pending action

Read effective_decision for the terminal authorization outcome. Do not treat every non-pending status as ALLOW, or call an expired denial a human rejection.

Who can approve

The handler checks current membership and requires ADMIN/OWNER or the membership’s can_approve permission. Separation-of-duties rules add requester/approver constraints where identity is available. A caller-provided principal label is not a verified human identity.

The console uses /api/v1/checkpoints; device and API clients use /v1/checkpoints. API-key clients can inspect permitted checkpoint state but cannot resolve a checkpoint as a human.

For paged listing, use GET /v1/checkpoints?pagination=v1&limit=50, then preserve pagination=v1 and the original filters while passing cursor. Paged results include pagination.next_cursor, total_count and total_count_capped; a capped total is a lower bound. Legacy listing has a different response shape. Do not combine status with statuses.

Device-driven reviews follow their heartbeat/abandonment protocol. Native /v1/evaluate HOLDs created with an API key follow the rule’s expiry without device-heartbeat abandonment; API keys cannot use the device-only heartbeat route. Read-only checkpoint polling is not a heartbeat or approval.

Notification is not the source of truth

Desktop and linked Slack approvals are notification/resolution channels. Poll or inspect the checkpoint record when a notification is missing. Real-time delivery helps responsiveness but does not replace the stored state.

Resume correctly

Edge hooks implement their supported wait flow. Custom API callers must honor the evaluate contract. Proxy clients follow proxy HOLD. Approval of a checkpoint is not permission to execute an unrelated action.