# Rotate the CI access token

Source: https://docs.qualflare.com/docs/cli/ci-cd/rotate-tokens · Last updated: 2026-11-02

Replace an expiring Qualflare access token in CI with no failed uploads: create the new token, update the CI secret, run the pipeline, then revoke the old one.

To rotate the access token a CI pipeline uses with Qualflare, create a new token, put it in the pipeline's `QF_TOKEN` secret, run the pipeline once, then revoke the old token; you need the Editor role or higher in the project, on any plan.

Every token expires after 7, 30, 60 or 90 days (30 by default), including the **Default** token a new project may start with. When a pipeline's token expires, its upload fails with [exit code 3](https://docs.qualflare.com/docs/cli/troubleshooting#api-key-not-working).

## When to rotate

Rotate a CI token when one of these happens:

* **Expires soon** appears next to the token in **Project Settings** > **Access Tokens**. It shows in the last 7 days before the token expires, except on a 7-day token.
* The token's creator gets the reminder email, 7 days before the token expires (not for 7-day tokens).
* The token may have leaked, or its creator is leaving the project or losing the Editor role: rotate at once. A token never has more access than its creator, and other events end a token early too ([Why a token stops working](https://docs.qualflare.com/docs/api/access-tokens#why-a-token-stops-working)).

*Figure: When a CI token shows Expires soon, create its replacement, update the secret, then revoke the old one.*

## Before you begin

* You create the new token in **Project Settings** > **Access Tokens** (requires the Editor role or higher in the project).
* You revoke the old one from the ⋯ menu on its row (requires the Maintainer role or higher in the project); an Editor asks a Maintainer or Owner.
* The project has room for one more token. A project can have 20 tokens that aren't revoked, and expired tokens count until they're revoked.
* You can edit the secret in your CI provider's settings.

## Rotate the token

Rotate the token in this order, so that the pipeline always has a token that works.

### Step 1: Create the new token

In **Project Settings** > **Access Tokens**, click **Create Access Token**. Enter a **Name** that says which pipeline and when, such as `GitHub Actions 2026-11`, choose an **Expiration**, leave **Allow writes** off, and click **Create**. Copy the value now: it is shown only once.

Create it as someone whose role on the project will stay Editor or higher, because the token never has more access than its creator.

### Step 2: Put it in the CI secret

Replace the value of the secret the pipeline reads, usually `QF_TOKEN`, with the new token. Each provider page shows where that secret is stored: [GitHub Actions](https://docs.qualflare.com/docs/cli/ci-cd/github-actions#store-the-token), [GitLab CI/CD](https://docs.qualflare.com/docs/cli/ci-cd/gitlab-ci#store-the-token), [Jenkins](https://docs.qualflare.com/docs/cli/ci-cd/jenkins#store-the-token), [Azure Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/azure-pipelines#store-the-token), [CircleCI](https://docs.qualflare.com/docs/cli/ci-cd/circleci#store-the-token) and [Bitbucket Pipelines](https://docs.qualflare.com/docs/cli/ci-cd/bitbucket-pipelines#store-the-token).

With qualflare-action, update the secret that the action's `token` input reads, whatever its name.

### Step 3: Run the pipeline once

Start a run. `qf login <identifier> --force` saves the new token over the old one, and `qf <identifier> collect` uploads with it.

`qf login` doesn't check the token with Qualflare, so the upload is the test.

### Step 4: Revoke the old token

> **Warning:** Revoking takes effect at once: anything still using the old token, such as another pipeline, stops working.

In **Access Tokens**, open the ⋯ menu on the old token's row, choose **Revoke**, then confirm with **Revoke token**. As an Editor, ask a Maintainer or Owner to revoke it.

## Verify

After the rotation, you should see:

* In the run's log, `OK Saved identifier "ci". …` (with the job's identifier) and `OK Test results collected successfully`.
* The run's launch in [Launches](https://docs.qualflare.com/docs/runs/launches).
* The old token gone from **Access Tokens**: a revoked token leaves the list.

## Troubleshoot

These are the errors a CI token rotation can run into:

* `maximum of 20 access tokens per project allowed; revoke unused tokens before creating new ones`: revoke an expired or unused token first. Expired tokens count until they're revoked.
* `invalid or expired access token (status: 401)`, exit code `3`, after the rotation: the job still reads the old value, or another secret. Check which secret the job exposes as `QF_TOKEN` ([`invalid or expired access token`](https://docs.qualflare.com/docs/cli/troubleshooting#api-key-not-working)).
* `no project access (status: 403)`, exit code `4`: the new token's creator doesn't have the Editor role or higher on the project ([the token lacks access](https://docs.qualflare.com/docs/cli/troubleshooting#token-lacks-access)).
* **Revoke** is disabled, with `Ask a maintainer or owner to revoke this token.`: you are an Editor, so ask a Maintainer or Owner.
* Another pipeline fails after you revoke: it used the same token. Give it a token of its own.

## Next steps

* [Token management](https://docs.qualflare.com/docs/cli/ci-cd#token-management): one token per pipeline, with **Allow writes** off
* [Access Tokens](https://docs.qualflare.com/docs/api/access-tokens): create, use and revoke project tokens
* [Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication): how qf saves a token under an identifier