---
title: "Macaroons Escalated Quickly"
description: "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."
---

# Macaroons Escalated Quickly

[Fly.io](https://yomu.fyi/company/fly-io) · Jan 31, 2024

**Type:** Explainer

## Summary

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.

## Context

Fly.io found that its API tokens were too powerful and needed a way to scope them down and express roles. The project was scoped to replace OAuth2 tokens and support varied permission requirements on a public cloud platform.

## Approach / What changed

The system uses user-linked HMAC-signed bearer tokens with chained caveats. Users can add restrictive caveats, while the implementation also provides first-party and third-party caveats, service-token transformations, machine locking, organization-specific SSO, and nonce-based revocation.

## Takeaways

- Each caveat is checked independently, and every added caveat can only weaken a token’s authorization; a token with no caveats is unrestricted and should not be honored.
- Fly.io models permissions through caveats covering organizations, apps, machines, and volumes, allowing users to create administrator, auditor, deployment, and other roles without platform changes.
- The implementation supports service tokens for longer-lived distributed workflows, machine-specific attenuation, nonce-based revocation, SSO, plugins, and traceable inter-service authorization, but restrictive caveats can express some roles awkwardly.

**Tags:** [Authentication](https://yomu.fyi/topic/authentication), [Macaroons](https://yomu.fyi/topic/macaroons), [Security](https://yomu.fyi/topic/security)

- Source: [Fly.io](https://fly.io/blog/macaroons-escalated-quickly)
- Source URL: https://fly.io/blog/macaroons-escalated-quickly
- Ingested by Yomu: 2026-09-02T12:00:49.695Z

[Read original post](https://fly.io/blog/macaroons-escalated-quickly)