Skip to main content
Agent approvals record human decisions about a proposed agent action in one workspace environment. They are separate from workflow-engine approvals, permission grants, cryptographic action receipts, and Temporal execution.

​
Before you start

  • Use an active agent from the same workspace and environment as your credential.
  • Create requests using a workspace API key or a signed-in workspace user.
  • Reviewers must be active human workspace members with the workspace-level tenant:governance:approve permission. An organization-only role is insufficient.
  • The requester cannot approve or reject their own request. Each reviewer may decide once. API keys cannot cast human votes.
In Console, open AI Agents → Agent Approvals. The request, review, and cancellation forms each have a dedicated page. Save the request link to return to it after it leaves the pending queue.

​
Create a request

This example requests two independent approvals in a one-hour window. Replace the agent identifier with an existing sandbox agent; a production agent cannot be used with a sandbox credential.
The 201 response contains id, requested_by, status: "pending", current_approvals: 0, and expires_at. Save id; creation does not publish the report or create a background workflow.

​
Review with a human session

Use Console for interactive decisions. If your integration uses the API, supply the reviewer’s short-lived workspace bearer session. Do not substitute an API key or embed a session token in source code.
The first approval in this example returns status: "pending" and current_approvals: 1. A different authorized reviewer must supply the second vote. Reusing the same reviewer returns a conflict. One rejection immediately changes the request to rejected regardless of earlier approvals. The service verifies current membership permissions, request ownership, expiry, and existing votes inside the decision transaction. Votes and the audit event commit together. Decisions cannot be edited or deleted through these APIs.

​
Check and enforce the outcome

The detail response includes the reviewer history. Only proceed when status is approved and the request still matches the exact agent, action, resource, and scope your application intends to use. Your application must also enforce current access permissions, agent status, and its own single-use or replay controls. These approval records do not provide an automatic execution or consumption mechanism. The review deadline limits when decisions can be submitted. It does not turn an already approved request into an expiring access token. Define any execution deadline in your own application.

​
Queue, cancellation, and errors

GET /v1/approvals returns an array of at most 100 oldest pending, unexpired requests. It has no pagination or historical-status filter. The queue omits individual decision history; fetch a request by ID for that history. The original requester can send POST /v1/approvals/{approvalID}/cancel with a nonblank reason. A request cannot be reopened after cancellation, rejection, approval, or expiry. Create a new request if the proposed action changes. These records support your review process; they do not establish SOC 2 compliance, ISO certification, identity-document verification, or the correctness of submitted evidence.