> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Approvals

> Gate task execution with human review or automated policy evaluation.

Some actions shouldn't run unattended. Approvals let you — or your policies — gate execution before it happens. An agent that drafts a customer email might proceed autonomously, but one that issues refunds should wait for a human thumbs-up. This is where you draw that line.

Approvals pause a task in `plan_review` until someone approves or rejects the plan. Policies evaluate automatically whether work should be allowed, denied, or require approval.

## Approval statuses

| Status      | Meaning                                                    |
| ----------- | ---------------------------------------------------------- |
| `PENDING`   | Awaiting a reviewer's decision.                            |
| `APPROVED`  | Approved; execution proceeds.                              |
| `REJECTED`  | Rejected; task moves to `cancelled`.                       |
| `CANCELLED` | Withdrawn before a decision was made.                      |
| `EXPIRED`   | Not decided within 24 hours (hardcoded; not configurable). |

<Warning>
  Pending approvals expire after exactly 24 hours. There is no way to extend this window.
</Warning>

## Policy outcomes

Policies evaluate a plan and return one of:

| Outcome            | Effect                                      |
| ------------------ | ------------------------------------------- |
| `ALLOW`            | Execution proceeds without review.          |
| `DENY`             | Execution is blocked immediately.           |
| `REQUIRE_APPROVAL` | An approval request is created; task waits. |

## How it works

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/approval-flow.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=6cd54b26df5a7dfac5ef3dac643d4101" alt="Approval flow" width="1535" height="1024" data-path="assets/diagrams/approval-flow.png" />

## SDK operations

### Approvals (`/v1/approvals`)

| Operation               | SDK                                                              |
| ----------------------- | ---------------------------------------------------------------- |
| List approvals          | `client.orchestrator.approval.list()`                            |
| Get approval            | `client.orchestrator.approval.get(approval_id)`                  |
| Review (approve/reject) | `client.orchestrator.approval.review(approval_id, decision=...)` |

### Policies (`/v1/policies`)

| Operation     | SDK                                                |
| ------------- | -------------------------------------------------- |
| List policies | `client.orchestrator.policy.list()`                |
| Get policy    | `client.orchestrator.policy.get(policy_id)`        |
| Evaluate      | `client.orchestrator.policy.evaluate(context=...)` |

## Review an approval

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    # List pending approvals
    approvals = client.orchestrator.approval.list()

    # Inspect one
    approval = client.orchestrator.approval.get("YOUR_APPROVAL_ID")
    print(approval["status"])  # PENDING

    # Approve
    client.orchestrator.approval.review("YOUR_APPROVAL_ID", decision="approve")

    # Reject
    client.orchestrator.approval.review("YOUR_APPROVAL_ID", decision="reject")
    ```
  </Tab>
</Tabs>

## Evaluate a policy

Test what outcome a given context would produce without creating a real task:

```python theme={"dark"}
result = client.orchestrator.policy.evaluate(
    context={"action": "send_email", "scope": "external"}
)
print(result["outcome"])  # ALLOW | DENY | REQUIRE_APPROVAL
```

## Errors

| HTTP  | Message                          | When                                               |
| ----- | -------------------------------- | -------------------------------------------------- |
| `400` | `invalid request` (with details) | Malformed review payload.                          |
| `400` | `invalid id`                     | The approval ID isn't a valid identifier.          |
| `404` | not found                        | The approval doesn't exist or isn't in your scope. |

## Security

| Requirement       | Detail                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Review permission | Reviewing an approval requires the appropriate RBAC permission for your organization.                                                                                     |
| Scoping           | Approvals are scoped to your organization, workspace, and environment.                                                                                                    |
| Expiry            | Pending approvals expire automatically after **24 hours** if no decision is made. Build approval review into your operational workflow so tasks don't stall indefinitely. |

## Rate limits

100 requests per organization per minute. Pagination: `page` >= 1, `page_size` 1–100 (default 20).

<AccordionGroup>
  <Accordion title="Common errors">
    | Code  | Meaning                               |
    | ----- | ------------------------------------- |
    | `404` | Approval or policy not found.         |
    | `409` | Approval already reviewed or expired. |
    | `422` | Invalid decision value.               |
    | `429` | Rate limit exceeded.                  |
  </Accordion>

  <Accordion title="Expiry behavior">
    When an approval expires (24h without a decision), the task moves to `cancelled`. There is no retry; submit a new task if the work should still be done.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Tasks" icon="list-check" href="/docs/orchestration/tasks">
    The work approvals gate.
  </Card>

  <Card title="Streaming & Replay" icon="play" href="/docs/orchestration/streaming-and-replay">
    See approval events in the stream.
  </Card>

  <Card title="Members & Roles" icon="users" href="/docs/iam/members-and-roles">
    Who can approve.
  </Card>

  <Card title="Tasks & Workflows" icon="sitemap" href="/docs/concepts/tasks-and-workflows">
    Where plan review fits in the lifecycle.
  </Card>
</CardGroup>

## Next steps

Continue to [Streaming & Replay](/docs/orchestration/streaming-and-replay).