---
title: "API Tokens: A Tedious Survey"
description: "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."
---

# API Tokens: A Tedious Survey

[Fly.io](https://yomu.fyi/company/fly-io) · Aug 24, 2021

**Type:** Explainer

## Summary

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.

## Context

Fly.io’s API access is currently all-or-nothing: users have root credentials, but the team wants fine-grained permissions for cases such as granting Grafana access to metrics or giving a contractor access to one application without exposing other applications’ secrets.

## Approach / What changed

The post surveys token designs, evaluating them through revocation, database access, and vulnerability concerns. It explains stateful random tokens, stateless platform tokens, OAuth 2.0, Macaroons, and Biscuits, including Macaroons’ planned use for the new permissions system.

## Takeaways

- Simple random tokens are easily revoked and expired, while keeping permission logic in ordinary API code; the post argues they are suitable for many applications, including long-term use.
- Platform tokens reduce database lookups by carrying signed or encrypted attributes, but create cache-consistency and revocation challenges; versioning users and storing versions in Redis is one described mitigation.
- Biscuits use Ed25519-based signatures and Protocol Buffers-encoded Datalog programs to express authorization rules, but fully using them may require moving most security policy into the tokens.

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

- Source: [Fly.io](https://fly.io/blog/api-tokens-a-tedious-survey)
- Source URL: https://fly.io/blog/api-tokens-a-tedious-survey
- Ingested by Yomu: 2026-09-02T12:01:05.903Z

[Read original post](https://fly.io/blog/api-tokens-a-tedious-survey)