Task mandates

A task mandate is permission for one task instead of one payment. The agent asks once, for example "buy 3 licences of the search API, at most 300 USD, within 2 hours". An owner or admin approves it once. While it is active, the payments of that task that would only wait for the approval threshold or an approval rule pass without asking again. It never lifts a cap, a deny, a security hold or the decision webhook.

Which problem does it solve?

• Cards cannot wait. Stripe gives Burnbound 2 seconds to answer a card authorization. A card payment that needs an approval is declined with approval_required, because nobody can approve in that window. A mandate approved beforehand lets that payment through.
• Approval fatigue. A task with ten payments over the threshold means ten approvals of the same thing. With a mandate, a person decides once, on the whole task: what it is for, how much, on which methods and hosts, for how long.
• Payments the user did not ask for. A mandate is narrow: an agent, a list of methods, optional hosts, merchants and payees, a budget and an end. That limits what a payment the agent is pushed into can take: one outside the scope, or one that hits a security hold a mandate never lifts, waits for a person as before. One inside the scope is covered, so keep the scope as narrow as the task.

How does the agent ask for one?

With the MCP tool request_mandate. Only the agent's own key (bb_agent_…) can ask, and only for itself.

Each optional list holds 1 to 20 values. A filter you give must hold: a payment that does not have the fact is not covered. An x402 payment has no merchant category, so a mandate with merchantCategories never covers one.

{
  "purpose": "Buy 3 licences of the search API for the Q4 report",
  "methods": ["x402.exact"],
  "hosts": ["api.example.com"],
  "maxUsd": "300",
  "maxPayments": 3,
  "durationMinutes": 120,
  "context": { "ticket": "OPS-1423" }
}

The answer carries the same fields as get_mandate_status (mandateId, status, usually pending, remainingUsd, expiresAt…), plus next (what the agent should do now) and, when the MCP server knows the dashboard's address, mandateUrl: the mandate's page in the dashboard. Clients that support URL-mode elicitation offer the user that page from the chat, as with a held payment, and approvalPrompt says what happened (opened, declined, cancelled, failed or unsupported). The text of that prompt is fixed: the amount and the duration, never the agent's purpose.

The request is refused, and nothing is asked, when:

How does it know where it stands?

get_mandate_status with the mandateId returns status, maxUsd, spentUsd, remainingUsd, maxPayments, usedPayments, durationMinutes, decidedAt and expiresAt. The agent only sees its own mandates: another agent's mandate reads as mandate_not_found. It never sees who decided or their note.

The time counts from the approval, not from the request: a 2-hour mandate approved at 10:00 ends at 12:00. If the agent waited on the chat prompt and the mandate was rejected or expired, request_mandate fails with mandate_rejected or mandate_expired. The agent should not ask again for the same task unless the user says so.

Who approves, rejects or revokes it?

Only an owner or an admin of the organization, signed in to the dashboard. The agent's key cannot, and nothing the MCP client answers in the chat decides anything. Members and viewers can see mandates, with the buttons disabled and the reason.

• Where: the approvals view has a task mandates tab next to held payments, and each agent's page has a task mandates section. The mandate's page shows the purpose as the agent wrote it, the scope, the budget, the duration and the declared context.
• Approve or reject a pending mandate, with an optional note of up to 500 characters. Approving needs a confirmation. With 20 mandates already active in the organization, approving fails with too_many_active_mandates.
• Revoke an active or exhausted mandate. It stops at once; what was already paid stays paid.
• Slack and email: a new mandate is announced like a held payment, through the same channels and with the same hourly limits: email on every plan, Slack on Team and up. The message shows our amount and duration in the headline, then the agent's purpose and scope as plain text after fixed labels, and the declared context as unverified. Its Approve and Reject buttons only open the mandate's page in the dashboard, where you confirm signed in.

Which payments does it cover?

A mandate only turns into an allow a payment the policy would hold for one of two reasons:

• threshold: its amount is at or above the agent's approval threshold;
• rule: an enforced custom rule asks for approval, the agent's, its subteam's or the organization's.

And only when all of this holds:

• the payment is the mandate's agent's;
• its method is in methods;
• it meets every filter given (hosts, merchant categories, merchant countries, payees);
• its amount in USD fits in maxUsd − spentUsd;
• a payment is left, if there is maxPayments;
• the mandate is active and before expiresAt.

If several mandates cover a payment, the one that ends first is used. A payment that does not fit waits for an approval as before: the mandate is not split or stretched.

What does it never cover?

A mandate never widens the policy. These apply exactly as without it:

• Denies: the maximum per payment, the daily cap, a person's sub-cap, subteam and organization budgets, limit and deny rules. The daily cap still applies to each day of the task.
• Security holds: a 402 that reads like instructions (instruction_like_description), the first payment to a new receiving address (new_pay_to), the first payment to a catalog host (catalog_new_host).
• The decision webhook: a payment your decision webhook holds keeps waiting, even if a rule also holds it.

The ceiling on maxUsd follows from this. A mandate cannot hold more than the agent may spend in the days it lasts: its daily cap times the days, rounded up, so 2 hours counts as 1 day. With a daily cap of 100 USD, a 2-hour mandate asks for at most 100 USD and a 3-day one for at most 300 USD. Above that, mandate_exceeds_caps says the most.

How is it used up?

• Each covered payment adds its amount in USD to spentUsd and 1 to usedPayments, in the same step that reserves the payment, so two payments at once cannot both take the last of it.
• When spentUsd reaches maxUsd, or usedPayments reaches maxPayments, the mandate becomes exhausted.
• A covered payment that fails or expires gives its amount and its count back. An exhausted mandate becomes active again.
• If another payment took what was left between the decision and the reservation, or a person revoked it, authorize answers agent_busy and the retry decides again with the mandate as it is now. A card in that case is declined.
• fetch_paid and stripe_refund return the mandateId that covered the payment.

Which methods can it cover?

Any payment method of the agent, through the same policy:

A mandate does not turn a method on. The method must also be allowed for the agent in its Payment methods (see Which ways can an agent spend?). Mandates are on every plan.

What goes into the audit?

Every change of a mandate is an audit event with the agent, mandateId, status, maxUsd, spentUsd, methods and expiresAt:

For each covered payment, payment.authorized carries the mandateId, and the payment records which mandate covered it. The policy's own decision is kept as it was, the hold, so the audit shows both what the policy said and which mandate let the payment through. If a Slack message or an email about a mandate fails, approval.notification_failed names the mandateId and the channel.