Guide // MandateGuard
How do role-scoped keys work for issuers, merchants and agents?
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
Role-scoped keys give every party to a shared mandate exactly the access its function requires. Issuer keys register and manage intents and mint further keys. Merchant and agent keys can read intents and verify receipts — and nothing else: they cannot register, modify, suspend or spend. Keys are minted from the MandateGuard registry with a label per party, shown once, listed by prefix and role, and revocable individually, so a counterparty change is a one-key operation instead of a programme-wide rotation. Never hand a counterparty your workspace key; mint them a role key instead.
What is a role-scoped key?
Role-scoped keys are API credentials minted on a MandateGuard workspace for parties to an intent, each carrying a role: issuer (writes — register and manage intents, mint keys), merchant (read and verify only), agent (read and verify only). Keys are shown once at minting, stored thereafter by prefix reference, labelled by the issuer, and individually revocable. The role travels with the key, so the same intent can be safely visible to parties with very different rights.
Why one shared credential fails shared mandates
A shared mandate tempts a shared credential, and a shared credential destroys the mandate's security story. If the merchant holds the same key as the issuer, the merchant can — in capability, whatever its intentions — alter the very budgets it is supposed to verify against. If the agent holds it, the mandate's limits are editable by the party they limit. Role-scoped keys replace the shared secret with differentiated capabilities: the credential itself encodes what its holder may do. Verification becomes trustworthy precisely because the verifier lacks write access: a merchant confirming your intent's budget cannot have quietly raised it first.
The three roles and their powers
The issuer role is the mandate's author: it registers intents, manages their status (suspend, resume, revoke), posts events and mints further keys. The merchant role reads intents and verifies receipts — the two operations a counterparty needs to honour mandate-backed orders with confidence. The agent role offers the same read-and-verify surface for the spending party, letting an agent confirm an intent's state and remaining budget before attempting a purchase. Role keys are minted by the issuer from the registry (POST /api/keys), with a label naming the holder, and the full key value is shown exactly once — the same show-once discipline as workspace and agent keys elsewhere in MandateGuard.
Labels, prefixes and the key list
Administration at scale is a naming discipline. Labels should name the party and the purpose (checkout-north, portal-south), because the key list — prefix, role, label, status — is what operators actually govern from. Prefixes let humans reference a key in conversation and incident notes without ever handling its value. When a verification fails at a merchant, the first diagnostic is which key, in which role, with what status: the list answers all three at a glance. Sloppy labels (key1, test, new) convert every incident into archaeology, and unlabelled keys tend to become immortal keys because nobody dares revoke an unknown.
Revocation as a routine operation
Keys must be revocable individually and instantly, and revocation must be boring. Relationships end, providers change, a key is pasted into the wrong ticket: each is a revoke-and-remint, not an incident, if the keys were scoped and labelled properly. The counterfactual shows the design's value: revoking a shared master credential mid-programme would break every party at once and force a coordinated rotation under pressure. With role keys, revoking Merchant South's key affects Merchant South only. Build the habit early — revoke at the first offboarding, however friendly — because key hygiene practised on easy cases is what makes it available on hard ones.
What role keys deliberately cannot do
Scoping is as much about exclusion as permission. No role key mints license upgrades, changes workspace policy, unfreezes agents or approves spending in the inbox; those remain owner functions behind workspace credentials. Merchant and agent keys cannot post spend events or register anything. And the intent service as a whole does not issue identity credentials — a role key authenticates a party's access to mandate state; it is not an agent passport and should never be presented as one. Keeping these boundaries explicit in your integration documentation prevents the slow scope creep where a convenient key gradually becomes a master key in practice.
Rolling keys out to counterparties
Onboarding works best as a small ceremony: agree the party's role and label, mint the key, transmit it through a secure channel (never in the same message as the intent_id and instructions), and have the party perform a supervised first verification — fetch the intent, verify a known receipt — before real orders depend on it. That first successful check proves connectivity, permissions and understanding in one step. Record in your own register who holds which label and when it was minted; the registry's key list is your counterpart. When the programme grows, this ceremony is the difference between a key estate you can describe and one you merely hope about.
Five actions to take now
- Mint one key per party, labelled with the party and purpose
- Give merchants and agents read-verify keys only — never the workspace key
- Keep issuer keys with the people who manage mandates, not with the agent
- Revoke a party's key the day the relationship or the person's role ends
- Test each key's limits at issuance: confirm merchant keys cannot write
Worked example: two merchants, two keys, one change
An issuer onboards two merchants to an intent programme. Merchant North receives a merchant key labelled checkout-north; Merchant South receives its own, labelled portal-south. Both can fetch the intents that concern them and verify receipts at order time. Neither can register an intent, change a budget or suspend anything — attempts return errors, and the key list shows each party's prefix, role and status.
When South changes fulfilment providers mid-year, the issuer revokes portal-south in one action and mints a successor key for the new provider. North's key is untouched, the agent's key is untouched, and the intent itself never changed hands. Scoped, labelled, revocable keys turned a counterparty change into a one-line operations task.
Frequently asked questions
Can a merchant key register an intent?
No. Merchant and agent keys are read and verify only. Registration and management require issuer authority.
What does the key list show?
Each key's prefix, role, label and whether it is revoked — enough to administer keys without exposing their values.
Is the workspace key a role key?
The workspace key is the owner's master credential for the workspace. Role keys exist so you never hand it to counterparties.
Can one party hold several keys?
Yes — separate keys per system or purpose (checkout versus portal) limit the blast radius of any single revocation.
What happens to a revoked key's past verifications?
History stands: verifications performed while the key was valid remain part of the record. Revocation stops future use.
Keep reading
- What is an interoperable intent service for agent mandates?
- How do merchants verify an agent's receipt against an intent?
- When should you suspend, resume or revoke an agent intent?
Put the policy in force: spend envelopes · intent registry · approval inbox · how the proof works · all MandateGuard guides