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 cannot reach another agent’s mail or machines, or your billing settings. It can use vault credentials and connected accounts explicitly shared with its agent within the token’s scopes. Organization key: A broader key issued from Settings → Organization keys in the dashboard. Use it to create agents and issue their tokens programmatically, such as when provisioning an inbox for a new tenant. It can also access organization resources within its granted capabilities. 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
`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 (Sign in with Agent Loadout)
`identity:share_owner`	Let such apps learn the organization’s accountable owner

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.

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
https://agent-loadout.com/.well-known/oauth-protected-resource/api/v1

Resources An OAuth access token works with the MCP server and the REST API alike. A resource parameter (RFC 8707) may name either:

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

To let a Vercel deployment request these tokens at runtime, see Vercel Connect. 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

Webhooks

Vault

Machines

MCP

Sign in with Agent Loadout

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