> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-loadout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate Requests to the Agent Loadout REST API

> Every API request needs a Bearer token. Learn about agent tokens, organization keys, OAuth 2.1 scopes, and how to issue tokens programmatically.

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:

```bash theme={null}
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:

```bash title="Issue an agent token" theme={null}
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:

```bash title="Create an agent with an inbox" theme={null}
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.

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

**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.

<Warning>
  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.
</Warning>