API token

An API token is the credential your integration uses to authenticate with Prefactor — it is how a running agent proves to the platform which account it belongs to and, in the case of a deployment token, which agent it is.

Account tokens and deployment tokens are the two scopes you should use day to day. Choosing the right one depends on what you need to identify at runtime. Environment-scoped tokens may still appear in the web app from older or programmatic creation; they are not creatable there.

Account tokens

An account token grants access to the whole account. Any SDK or script authenticated with one can send activity for any agent in the account and read data across all of them via the API. You pass the agent identity separately when using an account token — the token itself says nothing about which agent is running.

Account tokens are suited to scripts, CI pipelines, or administrative access where you need account-wide reach rather than agent-specific identity.

Deployment tokens

A deployment token is scoped to a single agent deployment — one agent in one environment. The agent identity is built into the token, so an SDK authenticated with one does not need to pass an agent identifier — Prefactor knows which agent the activity belongs to from the token alone. This is the recommended way to instrument a deployed agent, because it ties the running code to a specific agent and environment without any extra configuration.

Environment-scoped tokens

Environment-scoped tokens may appear in the Account › API tokens tab if they were created programmatically or through a legacy flow. There is no interface in the web app to create new ones. Prefer account tokens for admin and CLI access, and deployment tokens for agent runtimes.

All creatable token types go through the same lifecycle: Active tokens authenticate requests; a token can be Suspended (disabled but recoverable) or Revoked (permanently invalidated). Revoked tokens can then be deleted.

In the web app

• Account › API tokens tab — create and manage account-wide tokens, view all tokens associated with the account.
• Agent › Deployments tab — create and manage deployment-scoped tokens for a specific agent.

Related concepts

• Account — tokens belong to an account and are managed from account settings.
• Agent — deployment tokens carry the agent identity and are the recommended way to instrument a deployed agent.
• Agent deployment — deployment tokens are issued for a specific agent deployment and carry its identity at runtime.
• Environment — deployment tokens are scoped to one agent in one environment.