API

Passwords vault

The Authenticator app's encrypted vault: the account and its sealed keys, vaults, items, devices and resets. The server stores ciphertext; every change is signed by the vault's own key.

See Passwords. These routes are at /v1/me/vault, reachable only with the Authenticator app's own sign-in (a mobile token issued to the authenticator app): organization keys, Caity and the other apps get 403. Item contents and vault names are encrypted on the phone before they're sent, so the server holds ciphertext, padded sizes and a little metadata (when things changed, which devices synced).

Signed writes. Reads need only the sign-in. Every request that changes something carries X-Vault-Signature: t=<epoch milliseconds>,d=<device id>,s=<signature>: an Ed25519 signature (base64url) by the vault's signing key over these lines:

cactive-vault/v1/request
<METHOD>
<path>
<t>
<device id>
<base64url SHA-256 of the exact body, or of "" without one>

t must be within 5 minutes of the server's clock (otherwise 403 with code: "clock" and serverTime). Making a vault is signed with the new vault's own key; a device that was removed gets 403 with code: "device_removed".

Revisions. Every write names the revision it replaces; a stale one gets 409, and the app merges field by field and tries again.

Resets. An unsigned DELETE asks for a reset: after 7 days, unless a device that can open the vault cancels it, the vault can be deleted and made again. The account's email address is told when a reset is asked for. A signed DELETE deletes the vault at once.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

Route	What it does
`GET /v1/me/vault`	Your Passwords vault as stored: `account` (the keyset sealed under your master password and Secret Key, the Argon2id settings and salt, the public keys) or `null`, `vaults` with their wrapped keys and counters, `devices`, a pending `reset` and `limits`. Everything that says what's in the vault is encrypted on your devices. From the Authenticator app's sign-in only.
`POST /v1/me/vault`	Makes your vault: the account, a personal vault and the first device, all sealed on the device and signed with the new vault's own key (`X-Vault-Signature`). `409` (`exists`) when you have one, unless its reset is due, when the old vault is deleted first.
`PUT /v1/me/vault/keyset`	Replaces the sealed keyset after a new master password or Secret Key, if `keysetRevision` is still current (`409` otherwise). Signed by the vault. Emails you.
`DELETE /v1/me/vault`	Signed by the vault: deletes it now (items, vaults, devices and keys; the log stays). Without a signature (you can't open it any more): asks for a reset (`202`, `reset`), which may happen 7 days later unless a device that can open the vault cancels it. Emails you either way.
`POST /v1/me/vault/reset/cancel`	Cancels a pending reset. Signed by the vault.
`GET /v1/me/vault/vaults/:vaultId/index`	The vault's counter (`revision`) and every item's `itemId`, `revision` and whether it was `deleted`, without ciphertext: devices compare it with their copy.
`GET /v1/me/vault/vaults/:vaultId/items`	Up to 100 items by id (`ids`, comma-separated): each item's sealed `key`, `overview` and `details` (absent for deleted ones), `revision` and times.
`POST /v1/me/vault/vaults/:vaultId/items`	Writes up to 50 `changes` (a sealed `key`, `overview` and `details`, or `deleted: true`), each only if the item is still at its `baseRevision` (`0`: new; deletes go first). Per change: `ok` with the new revision, `conflict` with the item as it is now, or `rejected` (`limit`: the plan's item limit). Signed by the vault.
`PUT /v1/me/vault/devices/:deviceId`	Registers this device (`name`, `platform`: `ios`, `android` or `web`) or renames it; signed by the vault with the device's own id. Up to 20 devices; a removed id can't come back. Emails you about a new device.
`DELETE /v1/me/vault/devices/:deviceId`	Removes a device; it stops syncing and wipes its copy when it next connects. Signed by the vault.
`GET /v1/me/vault/activity`	Your vault's log, newest first, kept a year: made, devices added and removed, master password or Secret Key changes, resets, deletion, and counts of changed items. Never contents.