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

# Approvals

> Which capabilities need a person's yes before they run, and how agents ask for it.

Some capabilities reach a real person or cannot be undone. Pramaan marks them, and the MCP server
never runs one for an agent without a person saying yes first.

## Which capabilities need approval

A capability needs approval when either is true:

* It is listed with `requires_approval: true` (in the SDK, `requiresApproval`). These reach or
  lock out a real person, for example `auth.user.ban` or `auth.invitation.create`.
* Its effect class is `external_irreversible` or `external_unknown_effect`: sending to a
  person, calls, payments, deletes.

Read-only capabilities and reversible ones without the flag run without asking.

The API only declares this. A direct API or SDK call runs as usual, so if your own app calls
these capabilities, ask your user before you call.

## Approvals for team members

If your organisation has team members (roles, invites and limits are set in the dashboard), a call
made as a member can need an approval that the API itself enforces. Send
`Pramaan-Member: <member id>` to act as a member. A call made as a member needs an approver when
the capability needs approval (above), or when its price is over the organisation's approval
threshold.

The approver is the member themselves, if they may approve. Otherwise send
`Pramaan-Approved-By: <member id>` naming a member who may approve (`GET /v1/members` shows
`may_approve` for each). You are telling Pramaan that this person said yes, so ask them first.
Without an approver the call is refused with `403 forbidden` and `error.reason:
"approval_required"`. Check the `reason`, not the message. A key made for one member can name only
that member in `Pramaan-Approved-By`.

In the SDK, pass `{ member, approvedBy }` in the call options. A call with a plain organisation
key and no `Pramaan-Member` is not gated.

## The rule for agents

Before running a capability that needs approval, show the user exactly what will happen, with
the exact inputs, and wait for an explicit yes.

## What the MCP server does

The [MCP server](https://docs.pramaan.dev/tools/mcp.md) enforces the rule itself:

1. The agent calls `run_capability` (or a named tool) for a capability that needs approval.
2. The server does not run it yet. It asks the person through the MCP client, for example:
   "Run auth.user.ban (Ban a user ...) with these inputs? `{ "userId": "user_123" }` This
   affects a real person."
3. The person ticks "Yes, run it" and accepts: the call runs with exactly those inputs.
4. They decline, cancel or don't answer within 10 minutes: nothing runs, and the agent gets
   `{ "ran": false, "reason": "declined_by_user" }` (or `"no_answer"`).

Every call asks again, so a changed input always needs a new yes. The agent cannot approve on
the person's behalf: an `approved` argument from the agent is ignored.

The question is shown with MCP elicitation. A client that does not support elicitation cannot
run these capabilities: the call is refused with the error code `approval_required`, and the
agent is told to ask the user. Run them from a client that supports elicitation, or from your
own app after asking your user. Your client's own tool-call timeout also applies while the
question is open.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.