> ## 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 and API keys on behalf of each agent. Either kind can also hold a TOTP authenticator secret. Credential values are returned only by operations that explicitly reveal or generate them. Keep those results out of logs and chat transcripts. Credential reads are recorded in your organization's audit history.

## List credentials

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

The response contains a `credentials` array and `next_cursor`. Pass `limit` (1 to 100, default 100) and the previous `next_cursor` as `cursor` to retrieve another page. A null `next_cursor` means there are no more pages. The list includes the agent's own credentials and credentials shared with it.

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

**id** `string`

Unique credential identifier.

**name** `string`

Human-readable label set when the credential was created.

**kind** `string`

One of `login` or `api_key`.

**totp\_enabled** `boolean`

Whether this credential has an authenticator secret configured.

**agent\_readable** `boolean`

Whether the agent may reveal the credential's value with `vault:use`.

## Get one credential

`POST /api/v1/vault/:id/reveal` returns a `credential` object containing its metadata, `username`, `secret`, and `notes`. Requires **vault:use**, and the credential must be marked agent-readable. The authenticator seed is not included; use the [TOTP endpoint](https://docs.agent-loadout.com/api-reference/vault/totp.md) for a current code.

```bash title="Reveal a credential" theme={null}
curl -s -X POST https://agent-loadout.com/api/v1/vault/<CREDENTIAL_ID>/reveal \
  -H "Authorization: Bearer $AGENT_LOADOUT_TOKEN"
```

> [!NOTE]
>
> Every credential read is recorded in the org's audit history, including which agent read it and when.

## 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 a password is generated, it is returned as `generated_secret` beside the `credential` object. Later reads use `POST /api/v1/vault/:id/reveal` or the `get_credential` MCP tool, require an agent-readable credential, and are audited.

### Request body

**name** `string` *required*

Human-readable label for the credential.

**kind** `string` *required*

Type of credential: `login` or `api_key`. Required on creation; it cannot be changed by an update.

**username** `string`

Username or email address. Used when `kind` is `login`.

**secret** `string`

Password or API key. Required for `api_key`. A login password is generated when this field is omitted on creation.

**generate** `boolean`

For a login, set to `true` to generate a new strong password instead of using `secret`. The result is returned as `generated_secret`. API keys must be issued by their provider.

**allowed\_origins** `array`

Exact HTTPS origins where the local connector may use this credential. A login requires at least one origin, such as `https://accounts.example.com`.

**totp** `string`

Base32 authenticator seed or `otpauth://totp/...` URI. Use this field to add TOTP without changing the password or API key. On update, an empty string removes TOTP.

**agent\_readable** `boolean`

Whether the agent may reveal values with `vault:use`. Defaults to `true` for credentials created by an agent. Only an owner or admin can make a human-created restricted credential agent-readable.

**notes** `string`

Account notes or recovery codes, up to 4 KB. Notes are included when the credential is revealed.

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

Supply only the fields you want to change. Omitted fields retain their values. An agent can update its own credentials; credentials shared with it are managed by their owner.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.