STACK
MENU
DOCS / CONTROLS / APPROVALS

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.

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

prompt
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. Whether purchases and orders wait for you at all is The trust switch.

Approvals | Docs