---
title: Create a deployment token
description: Create an API token scoped to one agent and environment for your
  deployed agent.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

When you deploy an agent to an environment, give it a token that only works for that agent in that environment. If the token leaks, it can't touch your other agents, and your integration doesn't need to send the agent ID because the token already carries it.

By the end you'll have a deployment token copied somewhere safe and listed on the agent's Deployments tab.

## Before you start

- You have the **Full access** role on the account. Read-only users still see **Create deployment token**, but Prefactor refuses the change with an error.
- The agent is registered and runs in your own code. The Deployments tab only appears for those agents. See [Register an agent](/guides/register-an-agent).
- The environment you're deploying to exists on the [Account › Environments tab](/web-app/account/environments).
- You have somewhere to store the token, such as your secret manager. Prefactor shows it only once.

## Create the 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 **API tokens** list shows the agent's existing deployment tokens, one table per environment.

3. Select **Create deployment token**.

   The **Create deployment token** dialog opens. Tokens created here expire after two years.

   ![The Create deployment token dialog with Environment and Role selects above the Create token button.](../../../assets/screenshots/guides/create-deployment-token-dialog.png)

4. Choose the **Environment** the agent runs in.

   If the agent has no [agent deployment](/platform/concepts/agent-deployment) in that environment yet, Prefactor creates one along with the token.

5. Choose a **Role**.

   Pick **Full access** for a running agent: it records runs and spans, and a **Read only** token is refused for anything that changes data. Read only suits a dashboard or script that only reads this agent's data.

6. Select **Create token**.

   The **Deployment token created** dialog opens with the token under **Your deployment token** and a **Save this token now** warning.

7. Select the copy button next to the token and store the value.

   Prefactor confirms with "Deployment token copied to clipboard". Paste the value into your secret manager or deployment configuration now.

8. Select **I've saved the token**.

   The dialog closes and you can't see the value again. The new token is listed under its environment with an **Active** badge, its scope and role (for example "Agent deployment (Support agent · Production) · Full access"), and **Last used: Never**.

## Use the token

9. Set the token as `PREFACTOR_API_TOKEN` in the agent's environment, or pass it as `apiToken` in the SDK config, and leave the agent ID out.

   See [Configuration and environment variables](/sdks/configuration).

## Verify

After the agent runs with the new token, the token's **Last used** time on the Deployments tab updates, and the run appears on the agent's [History tab](/web-app/agent/history).

## If it didn't work

- **There's no Deployments tab.** The agent isn't one that runs in your own code. Hosted judges, for example, don't use deployment tokens.
- **Prefactor shows an error when you select Create token.** Your role is Read only. Ask a Full access user to create the token.
- **You closed the dialog before copying the token.** The value can't be shown again. Revoke the token from its **⋮** menu and create a new one.
- **The agent's requests are refused.** Check the token's badge on the Deployments tab. A **Suspended** token can be switched back on with **Activate**; a **Revoked** one can't. If the token is Read only, change it with **Update role**.
- **Runs show up in the wrong environment.** The token belongs to the environment chosen in step 4. Create a token for the right environment and swap it in.

## Other ways to do this

To create the token from a script, call [POST /api/v1/api_token](/api/platform/operations/actionapitokencreate) with the agent deployment scope.

## Related

- [API token](/platform/concepts/api-token) — token scopes, roles, and lifecycle.
- [Agent deployment](/platform/concepts/agent-deployment) — what a deployment pins in an environment.
- [Agent page › Deployments tab](/web-app/agent/deployments) — every column and action on the token list.
- [Account › API tokens tab](/web-app/account/api-tokens) — account-wide tokens, which also list deployment tokens.
- [Rotate an API token](/guides/rotate-an-api-token) — replace a token without taking the agent offline.