TL;DR This post introduces a new type of authentication token with more refined permissions. Deploy tokens are limited to managing a single Fly App and it’s associated resources
Authentication tokens are scary, messy, and a fact of life (at least if your life is anything like mine). When you run fly auth login, you get an API authentication token that gives flyctl, our API tool, access to do everything it needs to do–which is to create, configure, deploy and manage all of your org’s apps and all their resources. The downside of all this power is that a leaked, stolen, or misplaced token can cause you to have a really bad day.
Once you’ve got your app’s infrastructure configured just so, you’re probably just using flyctl to deploy your code. You might have even automated this process to run via a fancy CD pipeline when you merge a pull request. You shouldn’t have to give third-party services this scary-as-hell, all-powerful authentication token just to get one app deployed. And, now you don’t.
You can generate deploy tokens via fly tokens create deploy or via the Tokens tab on your app dashboard. These tokens are limited to managing a single Fly App and its associated resources1. You can use these tokens with flyctl by specifying them in the FLY_API_TOKEN environment variable.
Go ahead and try it out:
FLY_API_TOKEN=$(fly tokens deploy) fly deploy
1 Deploy tokens can manage the app and its volumes, machines, secrets, databases, logs, etc… Because you also need to connect to the app’s Wireguard network to monitor deploys, SSH into the app, or tail logs, these tokens also have the ability to create and manage Wireguard peers. This specific permission will become more fine-grained in the future.
Caveats
The caveat, or rather disclaimer, is that this is a new feature and there might be sharp edges. Take deploy tokens for a spin, but don’t rely on them for anything mission-critical just yet.
The Nitty Gritty
Under the hood, deploy tokens are our first use case for macaroons. We’ve written about macaroons before. Deploy tokens start off being all-powerful within a Fly.io organization and their permissions are attenuated by a sequence of caveats. The trick is that anyone with a macaroon can add more caveats to further attenuate the token’s permissions. This is all very exciting and cool. We’ll talk more about macaroons in another post and publish some code so you can mess with attenuating your own macaroons.
In the meantime, for those who are excited to geek out about macaroons, the caveats in a deploy token look something like this
[
org(myOrg: *),
validityWindow(from: now, to: nextTuesday),
ifPresent(
apps(myCoolApp: *),
orgFeatures(wireguard: *),
else: r
)
]
If this is confusing, don’t worry. The syntax is entirely made up and so are the semantics of our caveats.
