Tokens and Permissions: Scoped Access in Agent Loadout

A token is the credential you hand to an AI client. It identifies exactly one agent and carries a list of capability scopes you specified at issuance time. The client can only do what those scopes allow (read mail, use vault credentials, run a machine, or any combination) and nothing outside that list is reachable, no matter how the client asks. Tokens are the primary way you enforce least privilege in Agent Loadout.

Capability scopes

Every token is issued with one or more scopes chosen from the list below. A token without a scope has no access to that resource.

Scope	What it allows
`email:read`	List and read messages, threads, drafts, attachments, and mailbox counts
`email:send`	Send, reply, forward, manage sender rules, and manage the mailbox (move, label, delete)
`vault:metadata`	List the agent’s credentials with names and types, but without values
`vault:use`	Read agent-readable credential values and retrieve TOTP codes
`vault:write`	Create and update the agent’s own credentials
`wallet:read`	List the agent’s payment cards, spending rules, and transaction activity
`wallet:pay`	Reveal card details to complete a purchase
`compute:read`	List machines, read machine state, and read files on machines
`compute:run`	Create, start, stop, and resume machines; run commands; expose ports; write files
`compute:admin`	Permanently delete machines and open machine desktops
`connectors:use`	Use connected app accounts granted to the agent and inspect their request history
`phone:read`	List phone numbers, read SMS, wait for messages, and list sender rules
`phone:send`	Send SMS and manage SMS sender rules
`social:read`	Read granted social accounts, posts, analytics, conversations, and comments
`social:post`	Publish posts, reply to messages or comments, and moderate comments
`identity:sign_in`	Approve and deny sign-in requests from apps that show Sign in with Agent Loadout
`identity:share_owner`	Let such apps learn the organization’s accountable owner when they ask

Availability also depends on the capabilities enabled for your workspace and any account grants. A scope alone does not grant access to an unshared app or social account. email:send also requires email:read; wallet:pay also requires wallet:read. Request both scopes explicitly. Vault use and write require vault:metadata. Compute permissions follow compute:admin → compute:run → compute:read; compute:run does not grant admin access. Phone sending requires phone:read, and social posting requires social:read. Sharing the accountable owner with an app requires identity:sign_in alongside identity:share_owner.

Issue the minimum scopes the client actually needs. A coding agent that only signs up for services and reads mail does not need vault:write or compute:run. A CI-fixer agent does not need wallet:read.

Issuing tokens

You can issue a token from the dashboard or programmatically with an org key.

Dashboard
Org key API

Open the agent

In the dashboard, navigate to the agent you want to issue a token for.

Go to the Tokens tab

Click the Tokens tab on the agent’s page. Existing tokens and their scopes are listed here.

Create a new token

Give the token a name (e.g. claude-code or codex-cli), tick the capability scopes the client needs and click Create token. The token value is shown once; copy it before you choose Done.

Use an organization key (from Settings → Organization keys) to issue tokens programmatically: useful for multi-tenant setups or CI pipelines that provision agents automatically.

curl -s -X POST https://agent-loadout.com/api/v1/agents/<AGENT_ID>/tokens \
  -H "Authorization: Bearer $AGENT_LOADOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "claude-code",
    "capabilities": ["email:read", "email:send", "vault:use"]
  }'

The response includes the token value. Store it securely: it is not retrievable after the initial response.

Token boundaries

Tokens enforce hard boundaries that cannot be overridden at runtime:

A token can only reach the one agent it was issued for. It cannot read another agent’s mail or machines. Vault credentials and connected accounts explicitly shared with this agent remain accessible within its scopes.
A token never has access to billing, organization settings, or member management.
A token can use optional capabilities only when they are available in the workspace. Requesting a scope does not enable the capability.

MCP tokens (OAuth flow)

When a user connects an MCP client (Claude Code, Codex, Cursor, or ChatGPT) they go through an OAuth 2.1 authorization flow on the Agent Loadout site. The user chooses an agent, approves the scopes the client is requesting, and the platform issues an agent token. That token appears in the agent’s Tokens tab immediately and can be revoked there at any time. The MCP server URL for all clients is:

https://agent-loadout.com/api/mcp

OAuth discovery documents:

https://agent-loadout.com/.well-known/oauth-authorization-server
https://agent-loadout.com/.well-known/oauth-protected-resource/api/mcp
resource = https://agent-loadout.com/api/mcp

OAuth access tokens also work with the REST API, whose resource is https://agent-loadout.com/api/v1.

Token lifetime

Tokens created directly in the dashboard or organization-key API remain valid until revoked or until their configured expiry. The following lifetimes apply to OAuth tokens:

Token type	Lifetime
Access token	1 hour
Refresh token	Rotates on every use; expires after 90 days without use

Access tokens are short-lived by design. MCP clients and well-behaved REST clients use the refresh token to obtain new access tokens transparently. You do not need to re-authorize every hour.

Revoking tokens

Revoke a token at any time from the Tokens tab on the agent’s page: click the token row and choose Revoke. Revocation takes effect immediately; subsequent requests using that token are rejected. Revocation does not undo completed operations. You can also revoke through the standard OAuth revocation endpoint:

curl -s -X POST https://agent-loadout.com/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<TOKEN_VALUE>"

Organization keys

Org keys are a separate credential type used for management operations: creating agents, issuing tokens, and configuring the organization programmatically. They act for the organization within their granted capabilities. Keys with email:read or email:send can access organization mail; keys can also manage machines, phone numbers, or social accounts when granted the corresponding capability. They cannot reveal vault values or inject credentials into machines. Create them from Settings → Organization keys.

# Create a new agent with a ready inbox
curl -s -X POST https://agent-loadout.com/api/v1/inboxes \
  -H "Authorization: Bearer $AGENT_LOADOUT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "support",
    "display_name": "Support Agent",
    "metadata": {"tenant": "acme"}
  }'

Org keys are for your backend, not for AI clients. Never put an org key in an MCP configuration: issue a scoped agent token instead.

Best practices

One token per client

Issue a separate token for each client that connects to an agent: Claude Code, Codex, a cron job, a webhook receiver. If one client is compromised or behaves unexpectedly, you can revoke its token without affecting the others.

Least privilege

Only include the scopes the client actually uses. If you add compute:run to a token for a client that only reads mail, you have expanded the blast radius of a compromise with no benefit.

Rotate when a client changes

When you update a client’s system prompt, change its model, or hand it to a different team, issue a new token and revoke the old one. The token name in the Tokens tab tells you at a glance what each token is for.

Never log token values

Access tokens should never appear in application logs, CI output, or error reports. Use environment variables to pass tokens to clients and ensure your logging configuration excludes the Authorization header.

Get Started

Core Concepts

Guides

Account & Billing

Tokens and Permissions: Scoped Access in Agent Loadout

Capability scopes

Issuing tokens

Token boundaries

MCP tokens (OAuth flow)

Token lifetime

Revoking tokens

Organization keys

Best practices