Authenticate Requests to the Agent Loadout REST API

Every request to the Agent Loadout API must include a Bearer token in the Authorization header. The token you use determines which agent you act as and which capabilities you can exercise. There are no cookies, no API key query parameters — just the Authorization header on every call.

Token types

Agent Loadout issues two kinds of tokens: Agent token — Scoped to a single agent and the specific capabilities you granted at creation time. This is the token you give to an MCP client, embed in agent code, or store as a secret in your CI environment. It can never reach another agent’s data or your billing settings. Organization key — A broader key issued from Settings → Organization keys in the dashboard. Use it to create new agents and issue their tokens programmatically — for example, when you are onboarding a new tenant and need to provision an inbox in one API call. Store it as a server-side secret; never expose it to a client.

Passing the token

Include the token as a Bearer value in the Authorization header:

curl https://agent-loadout.com/api/v1/me \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"

OAuth scopes

Agent tokens are bound to one or more of the following capability scopes. Grant only what the agent needs.

Scope	What it allows
`email:read`	List and read messages
`email:send`	Send, reply, forward, and manage the mailbox
`vault:metadata`	List the agent’s accounts without revealing values
`vault:use`	Read agent-readable credentials and one-time codes
`vault:write`	Create and update the agent’s own credentials
`wallet:read`	View cards, rules, and card activity
`wallet:pay`	Reveal card details to complete a purchase
`compute:read`	List machines and read files on them
`compute:run`	Start, stop, and resume machines; run commands; expose ports
`compute:admin`	Delete machines and open their desktop

Issuing an agent token via the organization key

When you need to provision tokens in code — for example, as part of a tenant-onboarding flow — use your organization key to call the token-creation endpoint:

Issue an agent token

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 new token value. Store it immediately — it is not shown again. You can also create an agent with a ready inbox in a single call:

Create an agent with an 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","metadata":{"tenant":"acme"}}'

MCP OAuth 2.1

When an MCP client connects to the Agent Loadout MCP server, it authenticates via OAuth 2.1 with PKCE. Clients that support the MCP authorization spec handle this entirely automatically — you sign in once in the browser and approve the agent’s permissions.

If you are building your own MCP client or integrating with a framework that needs OAuth details, use the discovery documents below.

Discovery endpoints

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

MCP server resource

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

Token lifetimes

Access tokens are valid for 1 hour.
Refresh tokens rotate on every use and expire after 90 days without use.

Each OAuth authorization creates one agent token. It appears under the agent’s Tokens tab in the dashboard, where you can revoke it at any time.

Revoking a token

Revoke any token from the agent’s Tokens tab in the dashboard. Revocation also works through the standard OAuth revocation endpoint described in the authorization server metadata document.

Never include tokens in chat messages, application logs, browser-side code, or version control. Anyone who can read a token can act as that agent for the full duration of its validity.

Overview

Email

Vault

Machines

MCP

Authenticate Requests to the Agent Loadout REST API

Token types

Passing the token

OAuth scopes

Issuing an agent token via the organization key

MCP OAuth 2.1

Revoking a token

​Token types

​Passing the token

​OAuth scopes

​Issuing an agent token via the organization key

​MCP OAuth 2.1

​Revoking a token

Token types

Passing the token

OAuth scopes

Issuing an agent token via the organization key

MCP OAuth 2.1

Revoking a token