Workload & Agent Tokens

Workload Tokens (prefixed with agt_prod_... or agt_dev_...) are cryptographically signed, capability-scoped credentials used by production containers, CI/CD pipelines, and autonomous AI agents to authenticate against AgentSecrets Cloud.

Cryptographic Structure

Workload tokens are high-entropy cryptographic strings:

agt_prod_7f8a9b2c3d4e5f6a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a
 └──┬──┘  └──────────────────────────────────┬─────────────────────────────────┘
  Prefix                        256-bit Cryptographic Entropy

agt_prod_...: Scoped to production environments.
agt_dev_...: Scoped to development and staging environments.

Tokens are hashed using SHA-256 before persistence in the control plane database. The raw token is displayed only once upon creation.

Least-Privilege Capability Scopes

Workload tokens enforce granular capability boundaries to prevent over-privileged access:

Permission Scope	Type	Enforcement Behavior
`can_env_read`	`boolean`	Grants access to retrieve project environment secrets via `POST /api/workloads/env/` (used by `agentsecrets env`).
`can_proxy_resolve`	`boolean`	Grants permission to resolve placeholder handles via Cloud Resolver (`POST /v1/resolve` or proxy `:8765`).
`allowed_domains`	`string[]`	Restricts outbound calls to specific target hostnames (e.g. `["api.stripe.com", "*.openai.com"]`).
`allowed_handles`	`string[]`	Restricts resolution to specific secret names (e.g. `["STRIPE_KEY"]`).
`environment`	`string`	Binds the token strictly to an isolated environment (`development`, `staging`, or `production`).
`expires_at`	`timestamp`	Optional timestamp for automatic token invalidation.

Token Issuance Workflows

1Web Dashboard Issuance

Navigate to Workloads & Agents in the AgentSecrets Web App.
Click Issue New Token.
Select target environment (production), configure domain allowlists and secret handles, and generate the token.

2CLI Issuance

# Register an agent and issue its initial token
agentsecrets agent register billing-worker --env production

# Issue an additional token with a specific label
agentsecrets agent token issue billing-worker --env production --label "ecs-task-runner"

Production Deployment Patterns

1Docker & Kubernetes

Provide AGENTSECRETS_TOKEN via environment variables:

# docker-compose.yml
services:
  agent-runner:
    image: my-org/agent:latest
    environment:
      - AGENTSECRETS_TOKEN=agt_prod_7f8a9b2c3d4e...
    command: ["agentsecrets", "env", "--", "python", "main.py"]

2Cloud Platforms & Secret Managers

Configure AGENTSECRETS_TOKEN in your provider's secret storage:

AWS ECS / Fargate / Lambda: Add to Task Definition Secrets.
Render / Railway / Fly.io: Set in Environment Variables dashboard.
Vercel: Configure under Project Settings -> Environment Variables.
GitHub Actions: Store in Repository Secrets (secrets.AGENTSECRETS_TOKEN).

3Programmatic Agent Tool Calling (Python SDK)

When AGENTSECRETS_TOKEN is present in the container environment, the SDK automatically initializes cloud resolution:

from agentsecrets import AgentSecrets, credential

secrets = AgentSecrets()

response = secrets.call(
    "https://api.github.com/repos/my-org/backend/issues",
    method="POST",
    headers={"Authorization": f"Bearer {credential.GITHUB_TOKEN}"},
    body={"title": "Automated system alert"}
)

Revocation & In-Memory Eviction

When a workload token is compromised or rotated:

Revoke the token via Web Dashboard or CLI: agentsecrets agent token revoke <token_id>.
The control plane marks the token as revoked and broadcasts an invalidation event.
The Cloud Resolver evicts the SHA-256 token hash from volatile RAM within 2 seconds, immediately terminating subsequent resolution attempts.