# Approvals

How an action that a policy holds reaches you, how you decide it, what the agent does while it waits, and how you approve a held payment from a chat app. What approvals are and what they cost is on [Controls](/product/controls).

## Two kinds of approval

- A held action: your policy says a person must decide before one action of an agent runs. This guide is mostly about these.
- An approval of a change: you, or a tool acting for you, asked for something that widens what agents may do. It is covered at the end.

## Hold an action for a person

A policy holds an action in one of three ways:

```json
{
  "name": "Assistant",
  "actions": { "kinds": { "card.checkout": "review" } },
  "review": { "over_cents": 200 }
}
```

- actions.kinds set to review holds every action of that kind.
- review.over_cents holds any action that costs more than the amount.
- A rule for one connected service can hold calls to it.
- Setting these is in Policies.

## What the agent sees

The held call answers `403 CONTROL_DENIED` with the reason `review_required` and a reference:

```json
{
  "error": {
    "code": "CONTROL_DENIED",
    "details": {
      "reason_code": "review_required",
      "retry": { "ref": "crv_abc123", "after_seconds": 30 }
    }
  }
}
```

- Nothing ran and the action is not counted.
- The agent sends the very same call again later, with the reference: control_ref in a tool call, controlRef in the SDK, --control-ref in the terminal. Over the API it is the header X-Control-Ref.
- While you have not decided, the answer is review_pending. If you declined, it is review_rejected.
- Once you approve, the same call goes through. The agent has one hour to send it.
- The approval covers that exact call, once. A different call is held again.
- The agent is also woken when you decide, so it does not have to keep asking.

## Decide

```text
What is waiting for my approval?
```

The client calls `stack_list_control_reviews` and shows each held action with a link to its approval page. You decide on that page, signed in. From the terminal:

```bash
npx @getstackrun/cli reviews list
npx @getstackrun/cli reviews get crv_abc123
```

- Only the owner or an admin can decide.
- No tool, SDK method or command can decide for you. That is on purpose: a person decides, in a browser or in a chat app as below.
- A held action nobody decides expires after 24 hours.
- From code: stack.controlReviews.list({ status: "pending" }).

## Approve a payment from Telegram, a text or Slack

A held card or wallet payment can be approved from a chat app you have linked, within limits you set. Nothing else can be approved this way.

First set both limits in the policy. Turning this on counts as loosening:

```json
{
  "name": "Assistant",
  "review": {
    "over_cents": 100,
    "chat": { "max_per_payment_cents": 2000, "max_per_day_cents": 5000 }
  }
}
```

Then link your chat identity:

```bash
npx @getstackrun/cli chat link telegram
npx @getstackrun/cli chat link slack
npx @getstackrun/cli chat link sms --phone +14155550123
```

- Telegram: open the link the command prints and press Start. Slack: send the command it prints. A text: type the six-digit code you receive into the Console.
- Then confirm the identity in the Console, signed in. Until you do, it approves nothing.
- A prompt reaches only the owner's or an admin's linked identity. It works once and for ten minutes.
- A payment over either limit is not offered in the chat. Use the approval page.
- chat list shows your linked identities. chat remove ends one.

Whoever controls that phone number or chat account can approve payments up to your limits. Keep the limits small.

## Approving a change

When a call would widen what agents may do, it answers `403 GOVERNANCE_APPROVAL_REQUIRED` with a link. You approve, and the same call is sent again with the approval.

- In an AI client, most of these are asked right in the chat, with every part of the change listed. You answer there.
- Some are never asked in a chat and need the approval page in a signed-in browser: loosening a policy or controls, a held action, changing your own decision server, billing, deleting the account, changing its email, single sign-on, adding an install key, and approving an intent that can move money.
- From the terminal, the command prints the link, waits for you, and carries on.
- An approval works once and lasts 24 hours.
- stack_list_approvals and stack_get_approval read them. From the terminal: approval list and approval show \<id>.

## When it is refused

- 403 CONTROL_DENIED, reason review_required, review_pending or review_rejected - see above.
- 403 GOVERNANCE_APPROVAL_PENDING, _REJECTED or _EXPIRED - the approval sent with the call is not usable.
- 403 on a chat link step - typing the code and confirming an identity are done in the Console, signed in.
- 409 CONTROLS_NOT_ENABLED - controls are off, so no policy can hold anything.

## Reference

Writing the rules is in [Policies](/docs/controls/policies). Whether purchases and orders wait for you at all is [The trust switch](/docs/controls/trust).
