Skip to content
PrefactorPrefactorPrefactor Docs

Rotate an API token

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

Section titled “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, using Create API token.

Create the new token

Section titled “Create the new token”

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

    The Agent page 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

Section titled “Move the agent onto it”

  1. 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 for where the SDK reads the token. Until the agent restarts, it keeps using the old token, which still works.

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

Section titled “Revoke the old token”

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

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

Section titled “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.

If it didn’t work

Section titled “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 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

Section titled “Other ways to do this”

The API creates a token with POST /api/v1/api_token and revokes one with POST /api/v1/api_token/{api_token_id}/revoke. Run them with an account token, not the token you’re rotating.

Section titled “Related”