# Vault

> Keep the email and password of an account your agent made after its identity expires. Save, list, read, change and delete credentials, encrypted at rest, on Pro and Business.

Source: https://docs.dissolve.email/vault

Identities expire; the accounts made with them may not. The vault keeps the sign-in for a site (email, password, an optional persona and notes) after the identity is gone. Entries never expire. Pro holds 50 entries and Business 500.

Passwords and personas are encrypted at rest with a key held apart from the database. Listing never returns a password; reading one entry does, with `Cache-Control: no-store`.

> [!WARNING] The vault holds real passwords
> An OAuth connection needs `vault:read` to see them and `vault:write` to change them, and an unverified app must have vault access confirmed a second time on the consent page. Give these scopes only to apps you trust.

## Save a credential

`POST /v1/vault` (scope `vault:write`)

`email`, `password` and `siteName` are required. `category` is one of `social`, `shopping`, `dev-tools`, `testing`, `gaming`, `finance`, `news`, `entertainment`, `work` or `other`. `sourceIdentityId` records the identity it came from.

```bash cURL
curl -X POST https://api.dissolve.email/v1/vault \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "signup7f2k@dissolve.email", "password": "w8#Kq2!vLz9@pR4m", "siteName": "GitHub", "siteUrl": "https://github.com", "category": "dev-tools"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve();
const entry = await client.v1.createVaultEntry({
  email: identity.email,
  password: identity.password,
  siteName: 'GitHub',
  siteUrl: 'https://github.com',
  category: 'dev-tools',
  sourceIdentityId: identity.id,
});
```

```python Python
import os, requests

HEADERS = {"Authorization": f"Bearer {os.environ['DISSOLVE_API_KEY']}"}
entry = requests.post(
    "https://api.dissolve.email/v1/vault",
    json={"email": identity["email"], "password": identity["password"], "siteName": "GitHub", "category": "dev-tools"},
    headers=HEADERS,
).json()
```

```json
{
  "id": "vlt8Yh3NcQ2mZp5Rt0WxK",
  "email": "signup7f2k@dissolve.email",
  "siteName": "GitHub",
  "siteUrl": "https://github.com",
  "category": "dev-tools",
  "notes": null,
  "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA",
  "pinned": false,
  "createdAt": "2026-11-19T10:05:00.000Z",
  "updatedAt": "2026-11-19T10:05:00.000Z"
}
```

A full vault answers `429` with `limit_exceeded`.

### Straight from an identity

This route copies an identity's address, password and persona into a new entry without your code ever handling the password. It sits outside `/v1`, so it takes an API key (or the app's session), not an OAuth token.

`POST /api/vault/from-identity/{identityId}` (API key or signed-in session)

```bash cURL
curl -X POST https://api.dissolve.email/api/vault/from-identity/$IDENTITY_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteName": "GitHub", "siteUrl": "https://github.com", "category": "dev-tools"}'
```

With MCP, the [`save_to_vault`](/mcp/tools#save-to-vault) tool saves an entry the same way.

## List and search

`GET /v1/vault` (scope `vault:read`)

`search` looks in the site name, email and notes; `category` keeps one category. Pinned entries come first, then the most recently changed.

```bash cURL
curl "https://api.dissolve.email/v1/vault?search=github" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
const { entries, limit } = (await client.v1.listVault()) as { entries: unknown[]; limit: number };
```

```json
{ "entries": [{ "id": "vlt8Yh3NcQ2mZp5Rt0WxK", "email": "signup7f2k@dissolve.email", "siteName": "GitHub", "siteUrl": "https://github.com", "category": "dev-tools", "notes": null, "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA", "pinned": false, "createdAt": "2026-11-19T10:05:00.000Z", "updatedAt": "2026-11-19T10:05:00.000Z" }], "limit": 50 }
```

## Read one, with its password

`GET /v1/vault/{id}` (scope `vault:read`)

```ts TypeScript
const entry = await client.v1.getVaultEntry(entryId);
console.log(entry.password);
```

The answer is the entry with `password` and `persona` (the persona object, or null).

## Change and delete

`PATCH /v1/vault/{id}` (scope `vault:write`)

Changes `siteName`, `siteUrl`, `category`, `notes` or `pinned`. The email and password are fixed: save a new entry to change them. A body with none of these fields answers `400`.

```bash cURL
curl -X PATCH https://api.dissolve.email/v1/vault/$ENTRY_ID \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'
```

`DELETE /v1/vault/{id}` (scope `vault:write`)

```ts TypeScript
await client.v1.deleteVaultEntry(entryId);
```

## Import many at once

An import takes a JSON or CSV file of up to 1 MB and 500 rows, or the rows themselves. Like saving from an identity it is outside `/v1`: an API key or the session.

`POST /api/vault/import` (API key or signed-in session)

- `{"format": "json", "data": "<file text>"}`: an array of objects with `siteName`, `email`, `password` and optionally `siteUrl`, `category` and `notes`.
- `{"format": "csv", "data": "<file text>"}`: a header row naming Site Name (or Site), Email, Password and optionally Site URL (or URL), Category and Notes, in any order.
- `{"entries": [ ... ]}`: the rows as objects.

```json
{ "imported": 12, "failed": [{ "row": 4, "message": "email must be a valid email address" }], "skipped": 1, "overLimit": 0, "limit": 50 }
```

Rows missing a site name, email or password are `skipped`; rows that fail a check are listed in `failed`; rows past the plan's limit are counted in `overLimit` and not saved.

Every `/v1` vault endpoint is in the [Vault reference](/reference/vault).
