# Vault API

> Saved credentials, encrypted at rest. Every vault endpoint with its scope, parameters, body and an example answer.

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

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/vault` | [List vault entries](#list-vault-entries) |
| `POST /v1/vault` | [Save a credential](#save-a-credential) |
| `GET /v1/vault/{id}` | [Get a vault entry](#get-a-vault-entry) |
| `PATCH /v1/vault/{id}` | [Change a vault entry](#change-a-vault-entry) |
| `DELETE /v1/vault/{id}` | [Delete a vault entry](#delete-a-vault-entry) |

### List vault entries

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

Saved credentials without their passwords, pinned first (Pro 50 entries, Business 500).

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string | no | Words to find in the site name, email or notes. At most 100 characters. |
| `category` | string | no | Only this category. One of `social`, `shopping`, `dev-tools`, `testing`, `gaming`, `finance`, `news`, `entertainment`, `work`, `other`. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listVault();
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/vault", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

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

### Save a credential

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

Stores an email and password for a site, encrypted at rest.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | The sign-in address. |
| `password` | string | yes | The password. At most 1000 characters. |
| `siteName` | string | yes | The site, such as GitHub. At most 200 characters. |
| `siteUrl` | string | no | The site's address. At most 500 characters. |
| `category` | string | no | A category. One of `social`, `shopping`, `dev-tools`, `testing`, `gaming`, `finance`, `news`, `entertainment`, `work`, `other`. |
| `notes` | string | no | Free text. At most 1000 characters. |
| `persona` | string | no | A persona as JSON text, stored encrypted. |
| `sourceIdentityId` | string | no | 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","sourceIdentityId":"idn4Rk2PqT9wYc1Lm0ZxA"}'
```

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createVaultEntry({
  email: "signup7f2k@dissolve.email",
  password: "w8#Kq2!vLz9@pR4m",
  siteName: "GitHub",
  siteUrl: "https://github.com",
  category: "dev-tools",
  sourceIdentityId: "idn4Rk2PqT9wYc1Lm0ZxA"
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/vault", json={
  "email": "signup7f2k@dissolve.email",
  "password": "w8#Kq2!vLz9@pR4m",
  "siteName": "GitHub",
  "siteUrl": "https://github.com",
  "category": "dev-tools",
  "sourceIdentityId": "idn4Rk2PqT9wYc1Lm0ZxA"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```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"
}
```

### Get a vault entry

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

One entry with its password and persona.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The vault id. |

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

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getVaultEntry(entryId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/vault/{entry_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```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",
  "password": "w8#Kq2!vLz9@pR4m",
  "persona": null
}
```

### Change a vault entry

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

Changes the site, category, notes or pin. The email and password are fixed: save a new entry to change them.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The vault id. |

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `siteName` | string | no | The site. At most 200 characters. |
| `siteUrl` | string | no | The site's address, or an empty string to clear it. |
| `category` | string or null | no | A category, or null. One of `social`, `shopping`, `dev-tools`, `testing`, `gaming`, `finance`, `news`, `entertainment`, `work`, `other`. |
| `notes` | string or null | no | Free text, or null. At most 1000 characters. |
| `pinned` | boolean | no | Keep it at the top of the list. |

```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}'
```

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateVaultEntry(entryId, {
  pinned: true
});
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/vault/{entry_id}", json={
  "pinned": True
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "updated": true
}
```

### Delete a vault entry

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

Deletes the entry for good.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The vault id. |

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/vault/$ENTRY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

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

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteVaultEntry(entryId);
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/vault/{entry_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "deleted": true
}
```
