> ## Documentation Index
> Fetch the complete documentation index at: https://flox-kanishk-sat-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Service accounts

> Give CI and other automation an identity that belongs to your organization rather than to a person.

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](/concepts/organizations) 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.

<Note>
  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](/concepts/personal-access-tokens) instead.
</Note>

## Access levels

Every service account is created with one of two access levels, which apply
across the whole organization:

| Access level     | What it can do                                    |
| ---------------- | ------------------------------------------------- |
| **Read-only**    | Pull the organization's environments and packages |
| **Read & write** | Also push environments and publish packages       |

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](https://hub.flox.dev)
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

<Warning>
  The token is shown once and cannot be retrieved afterwards. Copy it into your
  CI platform's secret store before closing the dialog.
</Warning>

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:

```yaml title=".github/workflows/ci.yml" theme={null}
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      FLOX_FLOXHUB_TOKEN: ${{ secrets.FLOX_SERVICE_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: flox/install-flox-action@v2
      - uses: flox/activate-action@v1
        with:
          environment: my-org/my-env
          command: make test
```

The same variable works on every platform. See
[Running Flox in CI/CD](/tutorials/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`](/man/flox-auth):

```bash theme={null}
flox auth login --token-file ./token
```

## 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.