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

# Credentials API — Store and Retrieve Agent Secrets

> List, get, create, and update credentials in the agent vault. Requires vault:metadata, vault:use, or vault:write depending on the operation.

The vault stores logins, API keys, and TOTP secrets on behalf of each agent. Credential values never appear in chat transcripts or server logs — they are read through scoped API calls, and every access is recorded in the org's audit history.

## List credentials

`GET /api/v1/vault` returns account metadata only. Values are never included in the list response. Requires **vault:metadata**.

```bash title="List credentials" theme={null}
curl -s https://agent-loadout.com/api/v1/vault \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

<ResponseField name="id" type="string">
  Unique credential identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable label set when the credential was created.
</ResponseField>

<ResponseField name="kind" type="string">
  One of `login`, `api_key`, or `totp`.
</ResponseField>

<ResponseField name="username" type="string">
  Present when `kind` is `login`.
</ResponseField>

<ResponseField name="agent-readable" type="boolean">
  Whether the credential's value can be read by the agent via `GET /api/v1/vault/:id`.
</ResponseField>

## Get one credential

`GET /api/v1/vault/:id` returns the value of a single credential. Requires **vault:use**, and the credential must be marked agent-readable.

<Note>
  Every credential read is recorded in the org's audit history, including which agent read it and when.
</Note>

## Create a credential

`POST /api/v1/vault` stores a new credential. Requires **vault:write**.

```bash title="Create a credential with a generated password" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/vault \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Error tracker","kind":"login","username":"support@loadout.email","generate":true,"allowed_origins":["https://app.tracker.example"]}'
```

<Note>
  When `generate` is `true`, the generated password is returned **once** in the create response. After that, only `GET /api/v1/vault/:id` (or the `get_credential` MCP tool) can read it, and every read is logged.
</Note>

### Request body

<ParamField body="name" type="string" required>
  Human-readable label for the credential.
</ParamField>

<ParamField body="kind" type="string">
  Type of credential: `login`, `api_key`, or `totp`. Defaults to `login`.
</ParamField>

<ParamField body="username" type="string">
  Username or email address. Used when `kind` is `login`.
</ParamField>

<ParamField body="password" type="string">
  Explicit password to store. Mutually exclusive with `generate`.
</ParamField>

<ParamField body="generate" type="boolean">
  Set to `true` to have the vault generate a strong password. The value is returned once in this response only.
</ParamField>

<ParamField body="allowed_origins" type="array">
  List of origin URLs where this credential may be used by the local connector.
</ParamField>

<ParamField body="secret" type="string">
  Base32-encoded TOTP secret. Required when `kind` is `totp`. The raw secret is never returned by any endpoint after creation.
</ParamField>

## Rotate or update a credential

`PATCH /api/v1/vault/:id` rotates a password or adds a TOTP secret to an existing credential. Requires **vault:write**.

Use the MCP tool `update_credential` for the same operation from a chat client.

## MCP tools for the vault

Use these MCP tools when working from a client like Claude Code, Codex, or Cursor:

| Tool                | Scope required | Description                                               |
| ------------------- | -------------- | --------------------------------------------------------- |
| `list_credentials`  | vault:metadata | Account metadata without values                           |
| `get_credential`    | vault:use      | Value of an agent-readable credential                     |
| `create_credential` | vault:write    | Store a new account, optionally with a generated password |
| `update_credential` | vault:write    | Rotate a password or add an authenticator secret          |

<Tip>
  Issue tokens with only the vault scopes each client needs. A read-only integration needs only `vault:metadata`; one that fills in passwords needs `vault:use`; one that creates accounts needs `vault:write`.
</Tip>