Deploy Tokens

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.


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 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),
    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.



Are these tokens tied to a user? Or are they separate from the user access tokens?

Will there be an organization level token available soon? The use case is that we have multiple orgs for different environments and uses, mainly for isolation, and we’d like to have a token to allows pretty much full access to create/deploy/delete apps, volumes, machines, etc for only 1 specific org.

Tokens are tied to organizations. We track which user created a token, but that’s mostly informational. We could issue org-wide tokens today, but don’t have any UI for listing/revoking them, which feels kind of important.

FWIW, the workaround for now is to create a fake account for each org and use those accounts’ access tokens.

Is this something that can be done with the CLI?

1 Like

Not today. Sorry.

I hope this can be added someday/soon. I have a usecase I’m exploring and I don’t want to use the all powerful API token.

Is there a rough timeline for when we might be able to grant additional permissions so that the token could be used in a dev/CI pipeline to create and destroy apps on the fly (no pun intended)? The use case is to create an arbitrary number of temporary deployments for PR reviews.

1 Like

No timeline, but it’s on my TODO list.

Is this a thread for the feature explained in this page? It is a nice addition to the fly toolbox :slight_smile:

I tried using deploy tokens since this doc suggested to do so, and it turned out with a deploy token deployments with [release_command] section will fail with 401 Unauthorized in the log. What is interesting is actually, the release had succeeded. I guess it was not unauthorized to make a release but to spin up a temporary VM for release_commands which would have kind of super power.

It might be less confusing if the doc for Deploy Token mentions it cannot work with [release_commands] unless this is unintended.

Deploy tokens work with release_commands. That error likely means the release_command had a non-zero exit code or the release_command machine failed in another way.

We have a confusing error message/bug in flyctl where the deploy token is not authorized to read the application logs. The bug is we show that unauthorized to access the logs error instead of the error about the non-zero exit code. We’re fixing that error message. pr is here, which will be released shortly.

1 Like

Deploy tokens were supposed to allow log access, but there was a bug. That’s been fixed now and you should no longer see errors from the release-command stage of your deployments.

1 Like

@charsleysa @pmbanugo @mootari Organization-scoped tokens are now available: Org Scoped Tokens


Can we use deploy tokens to set secrets?

Awesome! Checking it out …

Yes. That should be possible.

1 Like