---
title: "Macaroons"
description: "3 posts about Macaroons, summarised, each linking to the original."
---

# Macaroons
> 3 posts about Macaroons, summarised, each linking to the original.

## Articles

### [Operationalizing Macaroons](https://yomu.fyi/post/operationalizing-macaroons.md)
- Company: [Fly.io](https://yomu.fyi/company/fly-io.md)
- Published: Mar 27, 2025
- Type: Explainer

Operationalizing Macaroons at Fly.io requires treating them as online-stateful bearer tokens whose nonces must be checked against database state, while keeping root secrets away from the primary API cluster. The team built tkdb, a roughly 5,000-line Go service backed by encrypted SQLite managed with LiteFS and Litestream, deployed on isolated hardware across the US, Europe, and Australia. Its HTTP/Noise interface supports verification and restricted signing, while FlyCast routing, retries, and client-side caching reduce the impact of unreliable global connectivity; verification caching exceeds 98%. Revocation uses blacklist state, and third-party caveats let services such as flyd obtain narrowly scoped secret-reading authority through tkdb rather than holding broad credentials. OpenTelemetry, standard metrics, and a retained OpenSearch audit trail provide visibility, while the post concludes that Macaroons’ internal infrastructure benefits outweigh limited user adoption.


### [Macaroons Escalated Quickly](https://yomu.fyi/post/macaroons-escalated-quickly.md)
- Company: [Fly.io](https://yomu.fyi/company/fly-io.md)
- Published: Jan 31, 2024
- Type: Explainer

Fly.io built a Macaroons-based security token system after finding its API tokens too powerful for expressing scoped permissions and roles. The design starts with a user-linked, HMAC-signed bearer token and chains caveats through HMAC, while checking every caveat independently so each added restriction can only weaken authorization. It models organizations, apps, machines, and volumes with first-party caveats, and also includes third-party caveats, service-token transformations, machine locking, nonce-based revocation, and expiration handling across customer workloads. The resulting system lets users create roles without changing the platform and supports SSO, plugins, and traceable inter-service authorization, although the author acknowledges extra complexity and awkward ways to express some roles.


### [API Tokens: A Tedious Survey](https://yomu.fyi/post/api-tokens-a-tedious-survey.md)
- Company: [Fly.io](https://yomu.fyi/company/fly-io.md)
- Published: Aug 24, 2021
- Type: Explainer

The post surveys API token schemes in the context of designing fine-grained permissions for Fly.io’s control-plane API, which currently provides all-or-nothing root credentials. It compares simple random tokens, platform tokens, OAuth 2.0, and other formats and protocols against revocation, database access, and vulnerability concerns, while distinguishing end-user API security from inter-service authentication and federated identity. The discussion explains how stateless signed tokens trade database lookups for cache-consistency and revocation problems, then presents Macaroons as a scheme the team plans to adopt, while noting that their expressiveness may be excessive for typical CRUD applications. Biscuits extend that model with public-key signatures and Protocol Buffers-encoded Datalog programs, offering unusually explicit authorization rules but demanding a potentially wholesale commitment to token-based policy. The conclusion favors simple random tokens for many CRUD applications, chooses Macaroons for the planned system, and advises against JWT.