Guide // MandateGuard
How do you integrate an authorize check before an agent spends?
By the Ingenious AI team · Published 2026-11-14 · Reviewed 2026-11-14
▸ Run the free live demo See pricing
Free covers 1 agent and 1 policy with the full authorize flow, signed receipts and the approval inbox — no card required to start.
Short answer
Integrating MandateGuard means putting one call — authorize — on the only path between your agent's intention to buy and the money moving. Setup is three steps: create a workspace, register the agent, attach its policy. At runtime the agent presents its agent key, the vendor, the amount and a task reference, and your code branches on ALLOW, DENY or REQUIRE_APPROVAL, redeeming a one-time token when a human approves. Keep payment execution separate, make task references meaningful, and fail closed if the check cannot be reached: an unchecked purchase is an unmade purchase.
What is the authorize call, exactly?
The authorize endpoint is MandateGuard's pre-spend check: the agent presents its agent key with a vendor, an amount and a task reference, and the engine evaluates the agent policy and returns a decision with a signed receipt. Integration means placing that call on the only path between the agent deciding to buy and money moving — every purchase, subscription start and renewal the agent initiates goes through it, with no alternate route holding live payment capability.
The shape of the integration
The integration has four objects and one call. You create a workspace and receive a workspace key. With it you register an agent and receive an agent key. You attach a policy — per-task cap, per-day cap, allowlist, approve-over — to that agent. Then, at runtime, the agent calls authorize with its key, the vendor, the amount and a task reference, and branches on the answer. Everything else in MandateGuard — the inbox, receipts, verify-chain, vendor trust — hangs off that skeleton. Notice what is absent: MandateGuard never takes the payment itself. Your agent still pays through your normal rails after an ALLOW, which keeps the policy layer independent of how any particular vendor charges.
Placing the call so it cannot be skipped
An authorize check that most purchases pass through is a reporting tool, not a control. The call must sit on the single path to payment inside the agent's tooling: the checkout function, the subscription tool, the provisioning command. If the agent has several tools that can each move money — a browser with saved cards, a marketplace skill, a cloud console — each one needs the gate, or better, the ungated ones need their payment capability removed. A useful design test is adversarial: describe to yourself how the agent could complete a purchase on its busiest day without a decision. Every route you find is an integration gap to close before the receipts mean anything.
Handling the three decisions in code
Write the branch before you write the happy path. On ALLOW, proceed to payment and persist the receipt sequence and hash with your task record, so your logs and the chain can be joined later. On DENY, stop that purchase, surface the reason to the operator channel, and return control — do not retry the identical request, and do not silently substitute a different vendor, because substitution after a denial is exactly the behaviour the allowlist exists to govern. On REQUIRE_APPROVAL, persist the pending state, notify whoever works the inbox, and suspend that purchase line until the token arrives. Agents that treat REQUIRE_APPROVAL as an error and crash tend to restart and re-request, filling the chain with noise.
Task references are an integration feature
The task reference looks like a courtesy field and behaves like a database key. Pass the identifier your own systems already use — the job ID, ticket, order or campaign — and every receipt becomes reconcilable: finance can prove which business object each decision belonged to, and duplicate investigation starts from references rather than timestamps. Placeholder references like test or job1 destroy that value for every future reader, including you. Decide the convention at integration time, enforce it in the calling code by refusing to call authorize without a reference, and the ledger will read like an annotated history instead of a pile of amounts.
Approvals and token redemption
When a request returns REQUIRE_APPROVAL, the human decision happens out of band in the inbox (or through your webhook-driven process). Approval produces a spend token; your agent redeems it once through the redeem endpoint, which checks the token's binding — this vendor, this amount — before completing the spend's receipt. Treat redemption failure as authoritative: the token was already used, bound to a different purchase, or never existed. Log it, stop, and escalate to a human rather than re-requesting in a loop. Single-use semantics mean a leaked token has a blast radius of exactly one pre-approved purchase, which is a property worth preserving by never logging tokens in plaintext.
Testing, failure modes and go-live
Test the integration against a real workspace with deliberately small caps: force an ALLOW, an over-cap DENY, an unlisted-vendor DENY and an approval round-trip, and confirm your code's branch for each. Then decide the outage policy in writing: if authorize is unreachable, purchases pause (fail closed) — any other choice silently converts a network problem into unbounded spending. Go live with the inbox staffed and the receipt review scheduled. The MandateGuard demo on the homepage runs this same flow against the live engine and is a handy reference for what correct first receipts look like.
Five actions to take now
- Create workspace, agent and policy before writing integration code
- Call authorize before every payment action, with a real task reference
- Branch explicitly on ALLOW, DENY and REQUIRE_APPROVAL
- Store receipt sequence and hash against your own order records
- Redeem approval tokens once, and treat redemption failure as a hard stop
Worked example: first week of an integrated agent
A team wires its enrichment agent in an afternoon. Policy: per-task cap 50 dollars, daily cap 150 dollars, approve-over 25 dollars, allowlist of two providers. Their code calls authorize before each provider checkout and stores the receipt hash on the job record. Day one in production, the receipts show 31 allows and 2 approvals — and one DENY where the agent, mid-task, tried a third provider a blog post recommended at 19 dollars.
The integration review that Friday is short because the evidence is complete: the team allowlists nothing new, notes the agent's source quality issue, and confirms every job record joins to a receipt. The authorize call did not just prevent a 19-dollar purchase; it made the first week of agent spending auditable by construction.
Frequently asked questions
What does the request contain?
The agent key, vendor, amount and task reference, as JSON to the authorize endpoint. The response carries the decision, the reason and the receipt.
Where do workspace and agent keys come from?
Creating a workspace returns a workspace key (shown once); creating an agent returns an agent key (shown once). Store both as secrets.
What if the authorize call itself fails?
Fail closed. A purchase that cannot be checked is a purchase that does not happen; log the outage and retry the check, not the payment.
Can I test before going live?
Yes — the homepage live demo runs the real API and writes real receipts, and you can build against your own workspace with small caps first.
Does authorize move the money?
No. MandateGuard decides; your existing payment path executes allowed spends. The engines are separate on purpose.
Keep reading
- How do MCP tools let an agent check its spending mandate?
- How does a one-time spend token work after approval?
- How do you set up your first AI agent spending policy?
Put the policy in force: spend envelopes · intent registry · approval inbox · how the proof works · all MandateGuard guides