Skip to main content
A service account is an identity your automation signs in with, such as a nightly test run or a release pipeline that publishes packages. It belongs to your organization rather than to the person who set it up, and it authenticates with its own tokens, which begin with flox_sat_. Without one, a pipeline has to sign in as a person. Its access is that person’s access, it stops working when they leave the organization, and revoking its credential also cuts off that person’s own CLI sessions.
Service accounts require Flox CLI 1.14.0 or newer. Earlier releases do not recognize the token format.They also require an organization. Personal FloxHub accounts cannot have service accounts, so to authenticate the CLI as yourself, use a personal access token instead.

​
Access levels

Every service account is created with one of two access levels, which apply across the whole organization: The access level belongs to the service account rather than to any one of its tokens, so every token issued to it has the same access, and that access cannot be narrowed to a subset of environments or packages. A service account is never an organization owner, so it cannot manage members, change organization settings, or create more service accounts. Creating a service account and issuing its tokens both require a signed-in owner, which means a leaked token cannot be used to create more credentials.

​
Creating a service account

Service accounts are created in FloxHub, and only by organization owners.
  1. Sign in to FloxHub
  2. Open your organization’s page
  3. Go to the Service accounts tab
  4. Select Create service
  5. Give it a name and choose its access level
Name the account after the job it does, such as release-runner or nightly-tests. The name is how you recognize the account later and has no effect on its access.

​
Issuing a token

A service account has no credential until you issue one. From the Service accounts tab:
  1. Select Issue token on the service account
  2. Choose how long it should last: 30 days (the default), 90 days, 1 year, or No expiration
  3. Copy the token
The token is shown once and cannot be retrieved afterwards. Copy it into your CI platform’s secret store before closing the dialog.
Service account tokens have no names of their own, since the service account is what identifies them. FloxHub lists each one by when it was created, when it expires, and when it was last used.

​
Using a token in CI

Set the token in the FLOX_FLOXHUB_TOKEN environment variable, which the Flox CLI reads without a separate login step. This example is a GitHub Actions workflow that reads the token from a repository secret:
.github/workflows/ci.yml
The same variable works on every platform. See Running Flox in CI/CD for the equivalent setup on CircleCI and GitLab. You can also write the token to a file and pass it to flox auth login:

​
Revoking a token

When a token is no longer needed, revoke it from the Service accounts tab:
  1. Find the token under the service account it belongs to
  2. Select the delete icon next to it
  3. Confirm
Revocation takes effect on the next request, so a job still running on that token fails at its next call to FloxHub rather than finishing on access it no longer has. Revoking one token leaves the service account and its other tokens working. Deleting the service account goes further: it revokes the account’s access to the organization and every token issued to it.

​
Rotating without downtime

A service account can have several live tokens at once, so you can replace one without leaving a gap:
  1. Issue a second token for the service account
  2. Deploy it to your CI platform in place of the old one
  3. Watch the old token’s Last used date until it stops moving
  4. Revoke the old token
This way the pipeline is never left with a token that has been revoked, so rotation needs no maintenance window.