Did you know? A service can give an AI agent a credential that the agent is allowed to make more restrictive before passing it to another worker, without first contacting the credential issuer for a new signature. A macaroon is one design for doing this. It starts with a cryptographically authenticated grant, and each added restriction—called a caveat—changes the authentication chain so that the holder cannot simply remove the restriction afterward.
That does not make macaroons a universal replacement for identity, consent or server-side authorisation. A secure receiving service must verify the entire chain, interpret every caveat, evaluate current context, resolve any required third-party discharge and check local account and resource policy. A macaroon is normally a bearer capability: someone who steals a still-valid one may exercise whatever authority remains inside its restrictions. Ordinary agent and automation systems can use these ideas today; artificial superintelligence has not been established.
Here is the working model: issue narrowly scoped capabilities, let delegated agents add restrictions rather than broaden access, deny unknown or unsatisfied conditions, preserve a verifiable event trail, and measure whether requests really stayed inside their granted authority. The examples below use deliberately invented data and do not claim that any live eduKate service or third-party system was tested.
Contents
- The practical problem: passing authority between workers without spreading a master credential
- What is a macaroon, exactly?
- Why caveats are cumulative rather than replaceable
- First-party caveats, trusted context and the importance of verification
- Third-party caveats and why a discharge is not an all-purpose permission slip
- Worked case: twelve resources, three delegated workers and explicit denominators
- The chained-HMAC intuition without misleading cryptographic promises
- An agent workflow that keeps authority smaller at every handoff
- Revocation, rotation and the limits of a bearer capability
- Macaroons, OAuth tokens and session credentials solve different jobs
- Verification matrix: distinguish authentic token, satisfied caveats and completed action
- Common failure modes and the direct repair for each
- Changed-context exercise: a delegated read becomes a publishing request
- Where this mechanism is limited or inappropriate
- Frequently asked questions
- Reader pathways and primary evidence
The practical problem: passing authority between workers without spreading a master credential
Imagine an educational document service where a parent asks an assistant to prepare a reading summary from one folder. The assistant may ask a document-extraction worker to read three files and a writing worker to produce a response. Neither worker needs the parent’s entire account, all folders or permanent permission to modify files. An unrestricted API key would make those distinctions dependent on voluntary good behaviour rather than enforceable boundaries.
One approach is to force every worker to ask a central authorisation service for its own narrowly scoped token. That may be reasonable, especially where online policy decisions or immediate revocation are essential. But cross-service delegation can be awkward when a worker must delegate only a fraction of an existing grant, and the issuer cannot be contacted for every subtask.
Macaroons address this by representing authority in a bearer token accompanied by caveats, each chained to the previous authenticator. An intermediary can append a restriction such as a short expiry or a specific operation. It cannot delete or edit a restriction and still present a valid chain without the needed secret. The verifier is responsible for checking the final credential and all its conditions.
The 2014 NDSS paper Macaroons: Cookies with Contextual Caveats for Decentralized Authorization in the Cloud by Birgisson and colleagues introduces this construction. The Google Research publication record describes its chained message-authentication codes and decentralised delegation. The claims are about a proposed credential mechanism and its prototype, not proof that deploying it automatically secures an AI agent.
An important mental separation follows: the token restricts the potential action, the verifier decides whether the complete request satisfies its restrictions, and the agent’s workflow determines when the action is attempted. Each layer can fail independently. An attractive capability string is not a substitute for those checks.
What is a macaroon, exactly?
A basic macaroon contains an identifier, information allowing the verifier to associate it with the issuing authority, a cryptographic signature and potentially an ordered collection of caveats. The issuing service uses a secret root key to authenticate the initial identifier. Subsequent caveats are incorporated into a chain, using the current signature as input to the next message-authentication-code calculation.
An HMAC is a keyed message-authentication code defined in RFC 2104. Unlike an ordinary unkeyed hash, it binds integrity to secret material. In the conceptual first-party macaroon chain, an issuer begins with an HMAC under its root secret, and each additional caveat advances the signature using the preceding authenticator as a key. The specific encoding, key derivation and third-party construction must follow the actual chosen library and protocol profile.
The design’s distinctive property is attenuation. A holder that knows its current signature can append another caveat without being able to recover the issuer’s root key. Removing an old caveat, reordering caveats or replacing a restriction breaks the chain verification. A person who received a read-only, short-lived capability cannot safely rewrite its caveats to claim permanent write authority.
Macaroons are not JWTs that happen to contain strings called permissions. A conventional signed JWT with issuer-held signing keys cannot generally be modified by an untrusted holder without invalidating its signature. A macaroon deliberately permits a special direction of holder-driven modification: further restriction. That distinction matters for architectures with chains of cooperating workers.
Neither credential format automatically answers whether a teacher, student or parent should have access to a particular file. The originating grant must be legitimate, the resource service must understand the conditions, and the active account policy must still be checked. The term capability describes a form of delegated authority, not a suspension of the surrounding security model.
Why caveats are cumulative rather than replaceable
Suppose a root capability permits reading one parent-authorised folder until 17:00. The coordinating assistant adds a restriction allowing only files ending in .txt. The extractor adds a further restriction of at most twenty read requests for that job. The effective authority is the intersection of all three conditions and any server policy, not the union. A later holder should not be able to ‘remove the limit’ by providing a new contradictory caveat.
Think of allowable request sets. Let A be requests matching the root permission, B those using allowed filenames and C those inside the read-count rule. The worker may perform requests in A∩B∩C only. If the server determines the current request is outside any one set, it denies the operation. There is no ‘most recent caveat wins’ rule that would turn C into a replacement for A.
A chain of restrictions can be empty even when each individual condition looks valid. For example, a root grant valid only until 17:00 and an added caveat valid only after 18:00 have no overlapping authorised time. The correct outcome is rejection. A verifier that tries to repair such contradictions by dropping the least convenient caveat destroys attenuation.
First-party caveats use conditions the target service can evaluate directly, such as an operation, resource prefix, expiry or request environment. An unknown condition cannot safely be assumed true. If a verifier cannot parse the predicate or lacks the information to determine whether it holds, it must deny under an appropriate fail-closed policy.
Design caveats with unambiguous semantics and namespaced meanings. A string such as ‘read files’ is too vague if one service interprets read to include export or listing private metadata. Define what is a permitted operation, which identifier names the resource and how the verifier treats path canonicalisation, case, aliases and symbolic links.
First-party caveats, trusted context and the importance of verification
A first-party caveat is evaluated by the receiving service. Its truth should be computed from trustworthy request context or authoritative state, not from an agent’s self-description. A worker might claim that the current time is before an expiry deadline; the verifier must consult its own appropriately synchronised clock instead of trusting an arbitrary timestamp in a chat message.
For a resource restriction, compare canonical resource identifiers. If a caveat says folder=/lessons/algebra, path traversal, percent-encoding tricks and alternate aliases must not allow access to /lessons/answers. The authorisation decision should happen after consistent resource resolution and before the sensitive read or write. It is not enough to use a naive string-prefix check where filenames can exploit ambiguous boundaries.
For a request-count caveat, the verifier typically needs state. A bearer token containing max=20 cannot, by itself, prove whether twenty earlier requests already occurred at other server replicas. A coordinated counter or other enforcement mechanism is necessary. Multiple workers racing on the same token require atomic accounting or a deliberately conservative budget. The caveat expresses a condition; it does not magically install enforcement.
Likewise, an expiry caveat requires both verification of the credential and an up-to-date clock policy. Distributed clock skew, cached authorisation results and long-running actions can make the boundary more complicated. For a write with serious consequences, rechecking authority at the commitment boundary is often safer than trusting a permission check performed an hour earlier.
Record which caveat failed without leaking secrets or personal data in diagnostic logs. A denial caused by unsupported syntax differs from a denial caused by an expired grant. Both should prevent the action, but their repair paths differ. The system should not silently expand scope to make a job complete.
Third-party caveats and why a discharge is not an all-purpose permission slip
Macaroons also support third-party caveats, which require evidence from another authority. Imagine a resource server that will allow access only if a separate consent service confirms that the requested action has appropriate user authorisation. The original macaroon records the third-party condition, and the agent must obtain a suitable discharge macaroon before the resource server can consider the full request.
The third-party mechanism protects caveat-related key material and verifies the discharge under rules that bind it to the original macaroon. An implementation cannot safely accept a generic signed note saying ‘consent granted’ for any token, any user or any document. Correct key handling, condition matching, discharge binding and expiration are essential. The original paper describes this mechanism more precisely than a conceptual summary can.
A discharge is not necessarily a long-lived grant. The external service may issue it only for a single context, time window or operation. If the consent service refuses or is unavailable, the receiving service must not assume that the user’s wishes have changed in the agent’s favour. Depending on the operation, the correct result is defer, deny or request an authorised human decision.
Third-party caveats illustrate a useful separation of duties. The resource server can enforce data access while a policy or consent service decides a particular condition. This can avoid embedding every authorisation fact in one credential. But it adds availability, expiry, identity-mapping and replay concerns. A system should use that complexity only when it earns a real security or delegation benefit.
Treat a discharge as evidence for its exact caveat, not as authority to override other restrictions. The first-party caveats remain in force. Even an authentic consent discharge for an allowed lesson file cannot create permission to edit an unrelated billing record.
Worked case: twelve resources, three delegated workers and explicit denominators
Consider a hypothetical folder with twelve files: eight learner-approved lesson notes, two answer keys and two private administrative documents. The parent authorises a coordinator to read only the eight lesson notes. That makes the root resource denominator eight permitted files out of twelve available, not twelve out of twelve. The fraction of the total folder represented by the root grant is 8/12=2/3, or approximately 66.7%.
The coordinator sends an extraction worker a macaroon additionally restricted to three named lesson files, each read at most once. The worker’s effective resource set contains three of the eight root-authorised files, or 3/8=37.5% of the root grant. Relative to the complete folder it contains 3/12=25%. These two percentages describe different denominators; a dashboard must not confuse them.
A second worker receives authority to read two distinct lesson files, and a third receives authority to read one other lesson file. Their delegations are separately scoped. Across the three workers, the maximum number of distinct lesson files accessible is 3+2+1=6, assuming no overlap. That is 6/8=75% of the root-authorised set, still not permission to read the two answer keys or two private documents.
Suppose the first worker attempts three allowed reads and one extra answer-key read. With appropriate verification, the three permitted actions succeed and the forbidden fourth request is denied. Its authorised-operation success is 3/3=100%, while its request acceptance is 3/4=75%. Neither percentage alone conveys the security outcome; the important distinction is that the forbidden action was blocked.
All counts are invented teaching numbers, not observed production logs. They demonstrate why capability scope, request count and actual resource outcomes need separate measurements. A successful HTTP response for the delegated job cannot establish that all restrictions held unless the resource service also verified the caveats at each protected action.
The chained-HMAC intuition without misleading cryptographic promises
The construction’s security purpose is to make caveat removal or modification detectable while allowing appending. Conceptually the issuer authenticates an identifier with a root secret. A new caveat uses the previous authenticator to advance the chain. Verification by an authorised service reconstructs the appropriate chain from trusted root material and rejects a credential whose final authenticator does not match.
Consider two hypothetical caveats: operation=read and expires=17:00. Appending expires=17:00 changes the final authenticator. A holder who deletes operation=read but retains the previous final signature cannot usually produce a matching chain for the altered caveat list without the necessary key material. The data and MAC no longer correspond. That is the integrity logic underlying attenuation.
Cryptographic integrity is only one boundary. A perfectly valid MAC says the encoded caveats were not tampered with according to the verifier’s policy; it does not establish that those caveats are meaningful or satisfied. A verifier must still interpret operation=read, compare the actual requested resource and evaluate time and other context.
HMAC is a well-studied primitive, but safe implementation needs proper key lengths, key derivation, message framing, approved algorithms, constant-time comparisons where appropriate and strong secret protection. Do not reimplement production macaroon cryptography from a paragraph in this article. Use a reviewed library that implements the relevant version and test vectors.
Because a macaroon is ordinarily bearer-based, copying its bytes can confer its restricted authority until expiry or revocation. A chained MAC does not prove physical identity of the person holding the credential. Consider secure transport, storage, short lifetimes, audience or device restrictions where supported, and authoritative server-side checks.
An agent workflow that keeps authority smaller at every handoff
Start when a trusted user authorises a specific job. The coordinator should establish the resource IDs, permitted operations, expiry and whether subcontracting is necessary. If a tool is not needed, do not create a credential for it. If a tool only needs to inspect a manifest, do not issue a write-capable credential simply because one is easier to construct.
At each delegation, append a restrictive caveat that limits the worker’s resources, operations and time. Log the delegation boundary using non-secret identifiers. The worker should not carry the parent capability into unrelated systems, and its prompt should not expose the credential to untrusted retrieved documents or output channels.
On every protected API request, the resource service verifies the macaroon chain, all first-party restrictions, third-party discharges when required and local policy. Only then should the operation be performed. For a consequential write, the decision may need to be repeated at commitment to handle revoked or expired authority in long-running workflows.
On a timeout, the coordinator should reconcile by an operation identifier before retrying. A previous write may have completed even though the response was lost. Capability-based access does not provide exactly-once business semantics. Use idempotency keys, state reconciliation and bounded retries as distinct controls.
After completion, the system reports what was actually read or changed, what was denied and which authorisation assumptions were verified. The user-facing explanation should not claim that a job respected its limits merely because no exception was raised. A useful audited workflow attaches evidence to individual resource actions.
Revocation, rotation and the limits of a bearer capability
Attenuation helps prevent expanding delegated authority, but it does not by itself revoke a stolen capability or force every disconnected server to learn that a user changed their mind. Revocation typically needs a short expiry, an authoritative denylist or epoch, a key or identifier change, or another coordinated policy mechanism. Each choice trades immediacy against availability, state and operational complexity.
Suppose a hypothetical capability permits reads until 17:00 but the parent withdraws consent at 16:15. If the resource service enforces only the embedded expiry caveat, the capability could remain usable for up to forty-five additional minutes. This arithmetic is 17:00−16:15=45 minutes, not a measured breach. If immediate withdrawal matters, the server needs an online or sufficiently fresh revocation check.
Rotating an issuing key can invalidate a population of tokens, which may disrupt legitimate workers as well as a compromised one. A granular revocation mechanism may be preferable when individual jobs need cancellation. Carefully define scope so the system does not cancel unrelated student sessions or active applications without permission.
Short-lived macaroons reduce exposure but can increase the frequency of authorisation requests. A design must specify acceptable stale-authority windows, failure behaviour when policy services are unreachable and how a human can stop a consequential job. If the service cannot determine current permission, silence or cached success is not proof of consent.
Confidential data should never be logged alongside bearer credentials as convenient diagnostics. Incident response should distinguish a copied credential from a modified one, local policy mistakes from cryptographic failures and a successful permitted read from an unauthorised disclosure. A macaroon makes some boundaries enforceable; it does not remove the need for system governance.
Macaroons, OAuth tokens and session credentials solve different jobs
An OAuth access token authorises access to resources under a specified grant and may be self-contained or opaque. Its scope and audience may be constrained by an authorisation server. A macaroon’s distinctive design allows holders to add verifiable restrictions while delegating, subject to the verifier’s interpretation. The two concepts can be combined in architectures, but no one should assume they are interchangeable because both are called tokens.
The related eduKate guide Agent OAuth Token Exchange explains subject, actor and audience boundaries in a standardised authorisation-server exchange. This article addresses a different reader job: locally attenuating a capability through appended caveats. The trust and audit requirements differ accordingly.
A browser session cookie may also be bearer-like, but standard web session management often relies on server-held state and invalidation. A macaroon is not a web session merely because the original paper compares the convenience of cookie-style credentials. Authentication, login state and delegated operation rights must be mapped separately.
A signed JWT and a macaroon have different signature and delegation properties. A JWT’s signature does not normally allow an untrusted holder to append enforceable caveats while preserving issuer verification. A macaroon’s chain makes particular attenuations possible, but requires all restrictions to be evaluated by the verifier. Selecting one format needs an explicit threat model and interoperability requirement.
Prefer established platform support and reviewed integrations to custom cryptography. An agent system should avoid introducing a new token format when simpler scoped OAuth grants, a short-lived server job ID or ordinary session controls already solve the problem with less risk.
Verification matrix: distinguish authentic token, satisfied caveats and completed action
A robust audit separates three questions. Is the presented credential authentic under the expected issuing key and chain? Are all its restrictions satisfied for the exact request at the current time and resource? And did the application perform only the permitted operation, with verified postconditions? Passing the first test is necessary but not sufficient for the others.
Consider five fictional requests: two reads of allowed lesson notes before expiry, one write to an allowed note under a read-only caveat, one read after expiry, and one read of a private administrative file. The correct protected-action outcome is two accepted, three denied. The request acceptance fraction is 2/5=40%; the policy-conforming decision fraction can be 5/5=100% if the system handled all five correctly. These metrics are not synonyms.
To verify such a system, construct negative tests that vary one boundary at a time. Try tampering with an existing caveat, reordering it, deleting it, substituting a discharge from another transaction, using an expired token and asking for a path outside the allowed canonical resource. Tests should confirm rejection, not just that the happy path works.
Measure conditions the server actually enforced. A caveat promising five allowed reads is not equivalent to a durable counter that atomically records five uses across all replicas. If concurrent requests can race, test the maximum simultaneous load and examine overrun behaviour. A secure design that cannot enforce a count should not offer that caveat as if it were reliable.
Report unresolved outcomes honestly. A timeout after submission could mean the request was processed but the response was lost. Ask the authoritative resource store or operation ledger before retrying the same consequential command. Do not reissue a broader capability simply to bypass the uncertainty.
Common failure modes and the direct repair for each
Failure one: the receiving service validates the chain but ignores an unknown caveat. Repair: require every caveat to be recognised and satisfied; reject unknown restrictions. Failure two: a worker appends a caveat but the server interprets it using attacker-supplied context. Repair: derive time, resource identity, request method and account policy from trusted server state.
Failure three: path restrictions are compared before canonicalisation, allowing traversal through aliases. Repair: resolve the authoritative resource identity before checking scope. Failure four: a stateful request-count caveat is implemented as a local in-memory counter on each replica. Repair: choose a coordinated atomic enforcement strategy or avoid the false promise of a shared maximum.
Failure five: a stolen bearer macaroon remains accepted after the owner withdraws consent. Repair: define revocation, short expiry and required online status checks for sensitive operations. Failure six: a third-party discharge is accepted without binding it to the correct original token. Repair: implement the documented binding and matching rules and test cross-token substitution.
Failure seven: the agent gives a worker its broad original root token rather than a restricted descendant. Repair: issue the narrowest practical delegated capability and keep the root credential out of tool-visible data. Failure eight: a successful MAC check is logged as proof of a successful business action. Repair: check the actual operation result and retain an outcome ledger.
Failure nine: a rollout rotates credentials without planning the verification overlap and revocation consequences. Repair: coordinate key lifecycle and intended token validity. Failure ten: a custom implementation invents its own encoding or HMAC inputs and produces credentials incompatible with peer libraries. Repair: use reviewed implementation guidance and official test vectors. Each repair preserves the principle that actual enforcement matters more than token aesthetics.
Changed-context exercise: a delegated read becomes a publishing request
Start with a macaroon allowing an agent to read three approved documents before 17:00. A helper adds a caveat allowing only one of those documents. The resulting capability has a narrower resource set and still permits only reading. Now change the task: the helper wants to publish a new document based on the summary. Can another caveat that says operation=publish grant that new power? No. Caveats can constrain existing authority, not expand the root read permission into a write or publish permission.
Even if a worker constructs a syntactically valid chained MAC with the added word publish, the total effective constraints are contradictory: read-only from the root and publish from the descendant. A verifier should deny the publication action. It must not treat the latest caveat as replacing the earlier permission. The user would need to make a separate properly authorised grant for publishing.
Change the scenario again. The worker may read the right document, but its token expired one minute before the request. A correct signature and the right path cannot rescue the expired request. The condition is time-dependent, and the verifier must use its own trusted time source. If the task is time-sensitive, request a renewed, properly scoped authorisation rather than deleting the expiry restriction.
Finally, imagine a third-party consent check required for that read. The consent authority issues a discharge for a different folder. It cannot be attached to the current transaction as a general permission. The receiving service verifies the bound discharge and its relationship to the original caveat, denying a mismatched assertion.
The changed problem teaches a transferable invariant: delegated authority must never broaden through subordinate actions. Authenticity, context and actual user permission are separate tests. A secure assistant can explain the denied request and seek appropriate authorisation, but it must not reinterpret a failed condition to complete the task.
Where this mechanism is limited or inappropriate
Macaroons are a particular credential construction, not a universal interoperability standard adopted by every cloud API. The original paper describes a design and evaluation, and real libraries vary in version, caveat vocabulary, discharge support and operational conventions. Check compatibility and security review before introducing them into an existing platform.
Bearer possession remains a core risk. Restrictions can reduce the damage from theft but do not automatically bind a capability to a real person or device. Sensitive systems may need additional authentication, secure storage, transport and revocation checks. Those controls may make a simpler online authorisation service preferable.
Third-party caveats introduce extra service dependencies and can fail because consent state or a discharge is unavailable. Such a failure may require human review or deferred execution rather than guessing. The ability to create sophisticated restrictions is useful only if every participating verifier implements them correctly.
Some predicates cannot be safely checked from a token alone. A maximum number of reads, a remaining financial limit or a rule conditioned on real-time consent may require authoritative shared state. Adding more words to a caveat cannot manufacture the required coordination or atomicity.
Use macaroons when their decentralised attenuation property solves an identified problem and a reviewed verifier can enforce the caveats. Use another mechanism when the threat model favours direct central approval, immediate revocation, standardised interoperability or simpler operational support. No identity scheme removes the need to validate real outcomes.
Frequently asked questions
What is a macaroon capability? A bearer authorisation credential whose chained message-authentication codes allow holders to append restrictions that verifiers can check.
Can a worker remove an unwanted caveat? Not while preserving a valid chain without the necessary secret material. Appending can attenuate authority; dropping earlier conditions breaks the intended authentication.
Is a macaroon an OAuth token? They are different credential designs. OAuth systems may provide scoped grants and token exchange; macaroons focus on holder-driven, cryptographically constrained delegation.
Does a valid HMAC mean an API request should succeed? No. It establishes part of credential integrity; the verifier must also check caveats, account policy, resource identity and current state.
What are first-party caveats? Conditions the receiving service evaluates itself, such as operation, resource, time or a server-enforced quota.
What are third-party caveats? Conditions requiring a suitable discharge from another authority, verified and bound to the original credential under the implementation’s protocol.
Can a macaroon be revoked immediately? Not automatically. Immediate cancellation generally requires a suitable authoritative policy or revocation mechanism, not just a static token.
Can a stolen macaroon be used? A bearer capability may be usable by whoever possesses it within its restrictions, unless further controls prevent use.
Should an AI agent keep a root macaroon in its prompt? No. Keep credentials in protected runtime handling and give tool workers only the minimum delegated authority.
Does this technology mean superintelligent agents exist? No. It is contemporary distributed-system authorisation engineering that can support ordinary assistants and service workers.
Reader pathways and primary evidence
If you are a student of computer security, draw a root capability, then three descendants with increasingly restrictive caveats. Show why A∩B∩C cannot permit a request outside A. Next calculate the 3/8 and 3/12 resource fractions in the worked example, stating exactly what each denominator represents.
If you build agent systems, start with a current privilege inventory, specify the authorised issuer and resource identities, and test the complete verifier, including negative cases. Make request-count and revocation semantics operationally real. Avoid handing raw broad capabilities to untrusted content or arbitrary prompts.
If you audit security, distinguish cryptographic chain integrity, policy predicates, user consent, replay handling and business-operation outcomes. Ask what happens when the verifier is offline, a discharge cannot be obtained, a key rotates or the credential leaks. A green signature check covers only one of those questions.
Primary sources: NDSS 2014 original Macaroons paper; Google Research publication page; and RFC 2104, HMAC. Related eduKate reading: OAuth Token Exchange and the How Super Intelligence Works hub.
Every file count, request and time in this article is an explicitly invented learning case, not a claim of a security test performed on a live institution. Effective security requires a verified implementation and system-specific review.