Skip to main content
Whether you’re deploying your app with GitHub Actions or running your own CD service, it’s best to avoid configuring deployment infrastructure with all-powerful tokens. Our access tokens use macaroons, which come with predefined scopes to reduce access from org-wide all the way down to running a specific command on a single app’s Machines. If you want all the details, you can read about our decision to use macaroons in our API Tokens: A Tedious Survey and Macaroons escalated quickly blog posts.
Important: We’ve previously suggested in docs and community that you should use the output of the fly auth token command as your API token for everything; this is no longer true. The auth token, sometimes called the “personal access token” or the “all-powerful auth token”, is a very short-lived token that is automatically created each time you log in with fly auth login. It’s used by flyctl to create, manage, configure, and deploy all the apps in any organization in your account. You should use tokens created with fly tokens deploy or fly tokens org instead. It’s always a good idea to use the token with the narrowest access that will work for your purpose.
You can create Fly.io access tokens with different predefined scopes using flyctl.

​
App-scoped tokens

Use an app-scoped token, sometimes just called a “deploy token”, to limit access to a single app. App-scoped tokens are useful for CI/CD pipelines where you need to share a token with a 3rd party. You can create a standard app-scoped deploy token, a token to SSH into an app’s Machines, or a token to execute commands on an app’s Machines.

​
Org-scoped tokens

Use an org-scoped token for access to manage all the apps within a single organization. An org-scoped token is the middle ground between the auth token and the more restricted app-scoped token, and is useful when you want to automate a single org. You can create a standard org-scoped token or a read-only org-scoped token.

​
Create and manage tokens

Create and manage tokens using flyctl. fly tokens create commands have some useful options for customizing your token:
  • token names: If you’re managing multiple tokens, then give the tokens custom names with the --name option to make them easier to find when you list them with flyctl or view them in your dashboard.
  • token expiry: When you create a token, include the duration that the token is valid for with the --expiry option. You should specify the shortest possible duration for your use case so that you limit access by time as well as scope. Tokens are valid for 20 years (175200h0m0s) by default.
For all options and commands, refer to the fly tokens command docs.

​
Create app-scoped tokens

App-scoped tokens are limited to managing a single app and its resources. Some organization-wide features like managing WireGuard tunnels are integral to deployments and are also accessible to deploy tokens. If you don’t specify a name with the --name option, then the default name is flyctl deploy token. Create an app-scoped deploy token with a custom name and expiry:
This example creates an app-scoped deploy token called staging one that’s valid for 48 hours:

​
Create an app-scoped token for SSH only

Create a token to SSH into a single app. The SSH token is scoped to only allow SSH access to a specific app and nothing else. To be able to SSH to an app, this token is also allowed to connect to the org’s WireGuard network. For example:
Use the token to SSH into the app:

​
Create an app-scoped token to execute commands on Machines

A machine-exec token can execute a restricted set of commands on an app’s Machines. You can specify commands on the command line or with the --command and --command-prefix options. If no command is provided, all commands are allowed. Create a machine exec token:

​
Create org-scoped tokens

Org-scoped tokens are limited to managing a single org and its resources, including apps. If you don’t specify a name with the --name option, then the default name is Org deploy token. Create an org-scoped deploy token with a custom name and duration:
This example creates an org-scoped deploy token called prod that’s valid for one week:

​
Create an org-scoped read-only token

You can further limit an org-scoped deploy token by making it read-only, which limits the token access to reading a single org and its resources. If you don’t specify a name with the —name option, then the default name is Read-only org token. Create a read-only org-scoped deploy token with a custom name and expiry:
Create a read-only token based on an existing token:

​
List or view tokens

List all the tokens for current app, or use the --app option to specify an app:
List all the tokens in an org, including org-scoped tokens:

​
Revoke tokens

  1. List the tokens and copy the ID of the token to revoke. Include the --scope org to list org-scoped tokens.
  2. Revoke the token:

​
Manage tokens in the dashboard

To manage app-scoped tokens, click an app, then click Tokens. From here you can revoke tokens or create new tokens. To manage org-scoped tokens, choose an organization from the dropdown, then click Tokens. From here you can revoke tokens or create new tokens.