---
title: Rotate an API token
description: Replace an agent's API token with a new one without taking the agent offline.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Swap an agent's API token without taking the agent offline, whether the old one is close to expiry, may have leaked, or belonged to someone who has left. You create the new token first, move the agent onto it, and only then revoke the old one, so there's no moment when the agent can't authenticate.

By the end, the agent is using a new token and the old one is **Revoked**.

## Before you start

- Your admin user has the **Full access** role. A Read only user can't create or revoke tokens.
- You can change the agent's configuration and restart or redeploy it.
- You know which token the agent uses and which environment it runs in. This guide rotates a deployment token, the kind an agent normally runs with. For an account-wide token, the steps are the same on the [Account › API tokens tab](/web-app/account/api-tokens), using **Create API token**.

## Create the new token

1. Go to **Agents** and select **View details** on the agent's card.

   The [Agent page](/web-app/agent) opens.

2. Select the **Deployments** tab.

   The agent's tokens are grouped into one table per environment. Find the old token and note its role. Its **Last used** time shows it's in use.

3. Select **Create deployment token**.

   The **Create deployment token** dialog opens.

4. Choose the same **Environment** and **Role** as the old token, then select **Create token**.

   The **Deployment token created** dialog opens and shows the new token value. This is the only time you'll see it.

5. Copy the value and store it where your agent reads its secrets, then select **I've saved the token**.

   The new token appears in the environment's table as **Active**, with **Last used** showing Never.

## Move the agent onto it

6. Set the new value as `PREFACTOR_API_TOKEN` in the agent's environment, or as `apiToken` in its SDK configuration, then restart or redeploy the agent.

   See [Configuration and environment variables](/sdks/configuration) for where the SDK reads the token. Until the agent restarts, it keeps using the old token, which still works.

7. Wait for the agent to run, then reload the **Deployments** tab.

   The new token's **Last used** now shows a time. Don't go on until it does: that's your evidence the agent has switched.

## Revoke the old token

8. Open the old token's action menu (**⋮**) and select **Revoke**, then confirm.

   The old token's status changes to **Revoked**, and Prefactor shows **Token revoked successfully**.

:::danger
Revoking can't be undone. Anything still using the old token fails to authenticate straight away. If you're not sure everything has moved, select **Suspend** instead: it stops the token the same way, but **Activate** switches it back on.
:::

Once a token is revoked, its action menu offers **Delete** to remove it from the list. You don't have to delete it; a revoked token can't be used again either way.

## Verify

On the **Deployments** tab, the old token shows **Revoked** and the new one shows **Active** with a recent **Last used** time. New runs keep appearing on the agent's [History tab](/web-app/agent/history).

## If it didn't work

- **The new token's Last used still shows Never.** The agent is still running with the old value. Check that the restarted process picked up the new `PREFACTOR_API_TOKEN`, and that nothing else, such as a `.env` file or a secrets cache, overrides it.
- **The agent stopped reporting after you revoked the old token.** Some process was still using it. Give it the new token, then check the [History tab](/web-app/agent/history) for new runs. A revoked token can't be restored.
- **The agent starts but records no runs, with authentication errors in its log.** The new token is for a different environment, or it's Read only. A Read only deployment token can't register runs or record spans. Create a Full access token for the right environment and switch to that.
- **You closed the dialog before copying the value.** Prefactor doesn't show it again. Revoke that token and create another.

## Other ways to do this

The API creates a token with [POST /api/v1/api_token](/api/platform/operations/actionapitokencreate) and revokes one with [POST /api/v1/api_token/{api_token_id}/revoke](/api/platform/operations/actionapitokenrevoke). Run them with an account token, not the token you're rotating.

## Related

- [API token](/platform/concepts/api-token) — token scopes and roles, and how tokens authenticate requests.
- [Agent page › Deployments tab](/web-app/agent/deployments) — every field and action on deployment tokens.
- [Account › API tokens tab](/web-app/account/api-tokens) — every token in the account, including account-wide ones.
- [Create a deployment token](/guides/create-a-deployment-token) — a first token for a new environment.
- [Configuration and environment variables](/sdks/configuration) — pass the token to the SDK.