Working with the Machines API

The Fly Machines API provides resources to create, destroy, and manage Fly Apps, Fly Machines, and Fly Volumes. Refer to the following reference docs for the usage of each:

Apps resource - Every Fly Machine belongs to a Fly App.

Machines resource - Fly Machines VMs themselves.

Volumes resource - Fly Volumes are persistent storage for Machines.

Connecting to the API

API addresses

There are two base URLs available to connect to the Machines API service.

Internal base URL: http://_api.internal:4280

Public base URL: https://api.machines.dev

From within your Fly.io private WireGuard network, you can connect to the API directly using the internal endpoint. From outside the Fly.io WireGuard mesh, use the public endpoint; this proxies your request to the API.

Authentication

All requests must include an API token in the HTTP headers as follows:

Authorization: Bearer <fly_api_token>

Replace <fly_api_token> with a Fly.io authentication token.

Environment setup

The examples in the Machines API reference docs assume that you have two environment variables set: FLY_API_TOKEN, the authorization token to use with the API call; and FLY_API_HOSTNAME, the API base URL.

For local development, you might set them as follows, assuming you have flyctl installed and have authenticated to Fly.io:

$ export FLY_API_HOSTNAME="https://api.machines.dev" # set to http://_api.internal:4280 when using WireGuard
$ export FLY_API_TOKEN=$(fly auth token)

The fly auth token command returns the token currently in use by flyctl. You can also create a new auth token in the Tokens section of the Fly.io dashboard.

To set an access token as an environment variable on Fly Machines, use a secret; for example:

fly secrets set FLY_API_TOKEN=$(fly auth token)