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

# Tokens and Permissions: Scoped Access in Agent Loadout

> A token identifies one agent and carries only the capability scopes you choose. Issue, scope, and revoke tokens from the dashboard or via the org key API.

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                                   |

<Tip>
  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`.
</Tip>

## Issuing tokens

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

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open the agent">
        In the dashboard, navigate to the agent you want to issue a token for.
      </Step>

      <Step title="Go to the Tokens tab">
        Click the **Tokens** tab on the agent's page. Existing tokens and their scopes are listed here.
      </Step>

      <Step title="Create a new token">
        Click **New token**, give it a name (e.g. `claude-code` or `codex-cli`), and tick the capability scopes the client needs. The token value is shown once — copy it before closing the dialog.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Org key API">
    Use an organization key (from **Settings → Organization keys**) to issue tokens programmatically — useful for multi-tenant setups or CI pipelines that provision agents automatically.

    ```bash 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 token value. Store it securely — it is not retrievable after the initial response.
  </Tab>
</Tabs>

## 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, vault, or machines.
* A token never has access to **billing, organization settings, or member management**.
* **Wallet and compute scopes are feature-flagged** — even if you include `wallet:read` or `compute:run` on a token, those capabilities do nothing until the feature is enabled in your workspace.

## 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
```

## Token lifetime

| 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; any in-flight request using that token will receive a 401 response on its next call.

You can also revoke through the standard OAuth revocation endpoint:

```bash theme={null}
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 do not act as an agent and do not have email or vault access. Create them from **Settings → Organization keys**.

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>