Access tokens

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:

fly tokens create deploy --name <"my token name"> --expiry <duration>

This example creates an app-scoped deploy token called staging one that’s valid for 48 hours:

fly tokens create deploy --name "staging one" --expiry 48h

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:

flyctl tokens create ssh -a my-app > my-app.token.ssh

Use the token to SSH into the app:

FLY_API_TOKEN=$(cat my-app.token.ssh) flyctl ssh console -a my-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:

fly tokens create machine-exec --command "<exact command and arguments to run>"

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:

fly tokens create org --name <"my token name"> --expiry <duration>

This example creates an org-scoped deploy token called prod that’s valid for one week:

fly tokens create org --name "prod" --expiry 168h

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:

fly tokens create readonly --name <"my token name"> --expiry <duration>

Create a read-only token based on an existing token:

fly tokens create readonly --name <"my token name"> --expiry <duration> --from-existing -t <existing token starting with fm2_>

List or view tokens

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

fly tokens list

List all the tokens in an org, including org-scoped tokens:

fly tokens list --scope org

Revoke tokens

List the tokens and copy the ID of the token to revoke. Include the --scope org to list org-scoped tokens.
```
fly tokens list
```
Revoke the token:
```
fly tokens revoke <token ID>
```

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.

Report an issue or edit this page on GitHub