Skip to content

Agent Tokens#

Agent tokens authenticate external agents and identify them as first-class principals in the platform. Each token represents a unique agent identity with its own team membership, project access, and audit attribution.

Creating a Token#

An administrator provisions an agent token with a descriptive name (e.g., "CI Pipeline Agent", "Data Sync Agent") and assigns it to a team. The team determines the policies and project access the agent inherits.

Token values are shown once at creation and stored as a one-way hash on the platform; the raw token cannot be retrieved again after provisioning.

Token properties#

Property Description
Identity Each token is a unique agent identity, separate from any human
Organization scope Scoped to a single organization
Team membership Assigned to a team, inherits team policies and project access
Audit attribution Every action is attributed to the token's identity
Storage Stored as a one-way hash — the original token cannot be retrieved

Token lifecycle#

Active use#

  • Tokens are validated on every request (hash lookup, revocation check, expiration check)
  • Last-used timestamp is updated on each authentication
  • Token works across multiple concurrent sessions

Revocation#

Revoke a token when it is no longer needed or may be compromised. Revocation prevents new authentications immediately. Existing connections continue until natural timeout or disconnect; the sandbox idle timeout (30 minutes default) bounds the window. For immediate termination, the agent's sandbox can be stopped directly.

Best practices#

  • Create one token per agent — avoid sharing tokens between agents
  • Use descriptive names that identify the agent's purpose
  • Revoke tokens for decommissioned agents
  • Review active tokens periodically

How Tokens Work With the MCP Endpoint#

External agents authenticate with their token against the organization's Lens Agents endpoint over MCP. The token is presented as a bearer credential; every subsequent tool call is authorized against the token's team and policy scope.

The endpoint address and the token value are provided during organization onboarding. See External Agents for the connection model.

Managed agent tokens#

Managed agents get tokens automatically — they are provisioned at agent creation and managed by the platform. You don't need to create or manage tokens for managed agents.