Approvals

Every tool call goes through one gate. The gate decides to allow it, ask a person or deny it. A call that needs a yes does not run. It waits as an approval until a person answers. This holds for agents, for workflows and for the MCP server. A tool call from an assistant over MCP acts as your Chief of Staff and follows the same rules.

What waits by default

Each tool has a risk class: read, write, send, money or live. live is the class for publishing or pausing an agent.

Class	Default
`read`	Runs.
`write`	Waits for a yes.
`send`	Waits for a yes.
`money`	Waits for a yes.
`live`	The person says yes on a card first.

Some tools have their own default. For example, a published agent answers its customers by itself, but a document it sends waits for a yes. A workspace can add its own rules for a tool, a risk class, an agent kind or one agent. A rule says allow, ask or deny. A rule for a department or a person can only make a call stricter.

What you see

When a call waits, the MCP result says so and does not run the action:

{
  "status": "waiting_for_approval",
  "approval_id": "APPROVAL_ID",
  "note": "This action did not run. It waits for a person's yes ..."
}

An approval has a status: waiting, approved, changed, declined or expired. It also has tool, risk, title, summary, terms, agent_id, requester, approver_id and times.

Answer through the API

List what waits for you:

curl "https://api.impellabs.tech/api/v1/approvals?state=pending" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can filter with state (pending or answered), tool, agent, risk and escalated. You see approvals where you are the approver, where they were escalated to you, or where you answered. Answer with one of three calls:

Call	Meaning
`POST /api/v1/approvals/{approval_id}/approve`	Yes. Run it.
`POST /api/v1/approvals/{approval_id}/change`	Do not run it. Send `{"note": "..."}` with what to change. The agent asks again.
`POST /api/v1/approvals/{approval_id}/decline`	No.

curl -X POST https://api.impellabs.tech/api/v1/approvals/APPROVAL_ID/approve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"terms": "TERMS_FROM_THE_APPROVAL"}'

terms is a hash of the tool and its arguments. If you send it, it must match the card. If the action changed since, the answer is refused and the action needs a new approval. Only the approver, or the person it was escalated to, can answer.

Timing

A waiting approval is reminded after 30 minutes. After 2 hours it is escalated: the approver’s manager, or an admin, can answer too. A card ends after 24 hours as expired. An approval step in a workflow ends with its own wait.

Allow it from now on

When you approve, send "always": true to make a standing permission. It lets that tool through without asking, within limits you set: per_day and max_items, each a whole number above 0. A permission is for you, or for the team when an owner or an admin gives it. Manage them at /api/v1/approvals/permissions. An owner or an admin can make a tool always ask with PUT /api/v1/approvals/always-ask and {"tool": "...", "on": true}. This turns its standing permissions off. Each member can also ask to approve every message their agents send, with PUT /api/v1/approvals/preferences and {"ask_before_sending": true}. It is off by default.

Rule changes

A change to a rule is also an approval. A person who cannot change a rule asks for the change, and the request waits for their manager and the owner.

Get started

Concepts