Skip to content

Encrypted records

Experimental end-to-end encrypted entries. The server stores opaque bytes and cannot read them; clients do all the cryptography.

GET /api/shared/vault

Read the sections other members shared with you

Auth: Session

The sections in the caller's active workspace that belong to other members and are visible to the caller: their audience is the workspace (or a group the caller is in) and the caller holds the vault-read permission. Each comes with ownerEmail, audienceKind, audienceGroups, editing, canEdit and the ids of its records, and those records in the collection API's form. Only records the section's owner created; files, aliases and request answers are left out. Encrypted records come as ciphertext. The same records are also open through the collection API, where members listed as editors can change them. People only.

Responses

Status Meaning
200 sections and records.
401 Not signed in.
403 An API key, or not a member.

GET /api/access/{collection}/{id}

Read who sees and who edits an item of the workspace

Auth: Session

collection is sections, records, links, requests, templates, contacts or attestations. Answers only for a member who sees the item; anyone else gets 404. Returns owner, readers and editors (each count, plus members with id and email for the owner and for members who may view members), canEdit, canChangeAudience, and for everything but a record audience (kind: private, workspace or groups; groups; editing: owner or audience). People only.

Parameters

Name In Required Notes
collection path yes
id path yes

Responses

Status Meaning
200 The item's access summary.
401 Not signed in.
403 An API key.
404 record_not_found: missing, or not visible to the caller.

GET /api/groups

List the groups of the active workspace

Auth: Session

Every group (id, key, name, members with id and email), and canManage: whether the caller may change them. Any member may list them. People only.

Responses

Status Meaning
200 groups and canManage.
401 Not signed in.
403 An API key, or not a member.

POST /api/groups

Create a group

Auth: Session

{name}, 1 to 80 characters; the key is derived from it. Needs the permission to invite members. People only.

Responses

Status Meaning
201 The group.
400 group_name_invalid.
403 missing_permission, an API key, or not a member.

PATCH /api/groups/{id}

Rename a group

Auth: Session

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The group.
400 group_name_invalid.
403 missing_permission.
404 group_not_found.

DELETE /api/groups/{id}

Delete a group

Auth: Session

Items whose audience named only this group are seen by their owner alone from then on.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
204 Deleted.
403 missing_permission.
404 group_not_found.

PUT /api/groups/{id}/members/{user}

Add a member of the workspace to a group

Auth: Session

Parameters

Name In Required Notes
id path yes
user path yes

Responses

Status Meaning
200 The group.
400 not_workspace_member: the user is not in this workspace.
403 missing_permission.
404 group_not_found.

DELETE /api/groups/{id}/members/{user}

Take someone out of a group

Auth: Session

Parameters

Name In Required Notes
id path yes
user path yes

Responses

Status Meaning
200 The group.
403 missing_permission.
404 group_not_found.

GET /api/sealed/state

Read your device list and wrapped workspace keys

Auth: Session

Experimental. The formats may change until they have been independently reviewed.

Everything returned is opaque to the server. A client must verify the device list before trusting any of it.

account is the caller's own account key, in the same shape as a workspace row and named account:<user id>, or null before any of their devices made one. Identity private keys travel under it.

Responses

Status Meaning
200 The caller's device list and key material.
401 Not signed in.
403 An API key cannot hold encryption keys.

POST /api/sealed/devices

Add to your device list and hand keys to your devices

Auth: Session

Experimental. Appends signed entries and stores wrapped workspace keys, and copies of the caller's account key (a wrap whose workspace is account:<user id>), in one transaction. Every entry must follow from the list before it and be signed by a device on it; a session alone cannot change the list. Removing a device withdraws its wrapped keys and refuses encrypted writes in those workspaces until a new key epoch exists.

An entry's kind is device, recovery or passkey. A passkey entry holds keys derived from a passkey's WebAuthn PRF output: it names its credential in credentialId, carries in anchorSignature the derived key's signature over revoked-passkey-anchor-v1 ‖ user ‖ root hash ‖ credentialId, and is never the first entry, so it is never self-signed. One live entry per credential. The PRF output itself never reaches the server: the sign-in page hands it to the app in the fragment of the revoked://auth link, and POST /api/passkeys/token names the passkey that signed in under meta.passkey (id, name, credentialId).

Responses

Status Meaning
200 Saved.
400 sealed_invalid: a malformed entry, or a key for a device not on the list.
403 Not a member of a named workspace.
409 sealed_version_conflict: the list changed first.

POST /api/sealed/workspaces/{id}/epochs

Start a workspace's encryption key, or replace it

Auth: Session

Experimental. Only someone holding the current key may replace it, and all of their live devices must receive the new one. Optional grants hand it to other members' devices in the same request, checked as in POST /api/sealed/workspaces/{id}/grants.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 Saved.
400 sealed_invalid.
403 sealed_key_missing: the caller does not hold the current key.
404 Not a member of this workspace.
409 sealed_version_conflict: the epoch is not the next one.

POST /api/sealed/workspaces/{id}/grants

Hand the workspace key to other members' devices

Auth: Session

Experimental. Body: epoch (the current one) and grants, each with user, deviceSeq, wrap, signerSeq, chainSeq (how far the caller's list had got), recipientChainSeq (how far the recipient's had) and signature, made by the caller's live device over revoked-grant-signature-v1 ‖ workspace ‖ epoch ‖ recipient user ‖ recipient HPKE key ‖ wrap ‖ granter user ‖ chainSeq ‖ recipientChainSeq. The caller must hold the current key and be able to invite members; each recipient must be able to read the vault and the device must be live on their list. Copies are never replaced. Each recipient is notified (sealing_access_granted).

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 Saved; granted lists the recipients.
400 sealed_invalid: a bad signature, or a device not on the recipient's list.
403 sealed_key_missing, missing_permission or not_workspace_member.
404 Not a member of this workspace.
409 sealed_epoch_stale (not the current key, or a new one is due), sealed_identity_keys_pending (an identity key in the workspace is still under its key), or sealed_version_conflict (that device already holds it).

GET /api/sealed/workspaces/{id}/members

Read every member's device list

Auth: Session

Experimental. Each member's user, email, isSelf, canRead (the server's word on whether they may read the vault), canGrant, holdsKey (whether any of their devices holds the current key) and devices, in the same form as in /api/sealed/state; epoch is the current one. Public keys only: no wrapped keys and no values. A client checks each list itself and remembers where it starts; the start is what a member's fingerprint is made from.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 Every member's device list.
401 Not signed in.
403 An API key cannot hold encryption keys.
404 Not a member of this workspace.

POST /api/sealed/account/epochs

Start your account key, or replace it

Auth: Session

Experimental. The account key is wrapped only to the caller's own devices and holds their identities' private keys, so a workspace key shared with other members never opens them. Wraps and their signatures use the workspace key formats with account:<user id> in place of the workspace id. Only a holder of the current key may replace it, the new key must carry the old one in priorWrap, and every live device must receive it. Removing a device that held it makes a new one due.

Responses

Status Meaning
200 Saved.
400 sealed_invalid.
403 sealed_key_missing: the caller does not hold the current key.
409 sealed_version_conflict: the epoch is not the next one.

POST /api/sealed/records

Create an end-to-end encrypted entry

Auth: Session

Experimental. The client chooses the id, because the ciphertext is bound to it. The entry's value stays empty. A link serves it as ciphertext, and only once it holds a seal for it (PUT /api/sealed/links/{id}); it does not appear in short links, sign-in grants or request answers.

An encrypted file (type: file, alpha) is sent as multipart/form-data: this JSON body in a meta field and the encrypted blob in a blob file field. Its name, media type and size travel inside sealedValue; the server stores the blob as encrypted.bin and keeps no name, hash or media type of its own.

Responses

Status Meaning
200 The saved entry.
400 sealed_invalid or sealed_record_unsupported.
403 sealed_key_missing, or no access to the workspace.
409 sealed_epoch_stale: reload the keys and encrypt again.

PUT /api/sealed/records/{id}

Encrypt an entry, or replace an encrypted entry's value

Auth: Session

Experimental. expectedVersion is compared atomically: 0 encrypts a plain entry, and a higher number replaces that version.

carryLinks: true preserves existing live links during encryption. For each link whose key the device can open, linkSeals supplies link, viewerWrap, writerWrap, expectedKeyWraps (the complete previous scope map, or {}) and, for a first key, keyWraps. A section's entry is added explicitly to the carried link. The seals, keys and entry commit together. Aliases and server-created grants cannot be carried. Remaining links require dropLinks: true; without confirmation the response is sealed_links_affected with a count, and nothing changes. Their owners receive an in-app notification. Without carryLinks, the previous explicit-drop behavior remains.

Replacing the value of an entry that live links carry takes linkSeals: for each link listed by GET /api/sealed/records/{id}/links, an object with link, viewerWrap and writerWrap, made for the version this write produces, plus expectedWriterWrap copied from the read. This comparison prevents a concurrent key replacement being undone by a stale record writer. Entry and seals are saved together. A write that leaves one of those links out is refused with sealed_link_seals_missing and the ids of the links it missed in links, and changes nothing.

For a file, the same body goes in a multipart meta field with the encrypted blob in blob. Encrypting a plain file requires the blob; renaming an encrypted file is a JSON write that keeps its blob.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The saved entry.
400 sealed_invalid or sealed_record_unsupported.
403 sealed_key_missing.
404 No such entry, or not one the caller may change.
409 sealed_version_conflict, sealed_epoch_stale, sealed_links_affected or sealed_link_seals_missing.

List the links a write to an encrypted entry has to renew

Auth: Session

Experimental. Answers with the entry's version and, in links, one object per link that carries the entry, can still be opened and holds a seal of that version: its link id and the writerWrap, which the entry's current value key opens. Paused links are included; revoked and expired ones are not.

For encrypted entries the caller learns that those links exist, including other members' private ones, and nothing else about them. For plain entries this instead returns only visible live links that can carry the entry during encryption: id, user, workspace, audienceKind and sealedKeyWraps. Private links of other members are never disclosed. Aliases and server-created grants are omitted.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 record, version and links.
404 No such entry, or not one the caller may change.

GET /api/sealed/links/{id}

Read what a link holds for encrypted entries

Auth: Session

Experimental. For a member who sees the link: keyWraps, the link's key per scope (the owner's account scope, and the workspace's id while the link is seen by more than its owner), each with epoch and wrap; and seals, one per encrypted entry with record, version and current. A seal that is not current was made for an older version of the entry and is not served to viewers.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 link, keyWraps and seals.
404 No such link, or not one the caller sees.

PUT /api/sealed/links/{id}

Put encrypted entries on a link

Auth: Session

Experimental. seals holds one object per entry: record, the entry's current version, viewerWrap (the entry's value key for the link's viewers) and writerWrap (the key to that wrap, for whoever writes the entry next). Each entry joins the link's records in the same transaction. The collection API keeps refusing an encrypted entry on a link; taking one off a link stays with it, and removes the seal.

keyWraps stores the link's key, which otherwise exists only in the link's address after #, per scope as {epoch, wrap}. The owner's account scope (account:<user id>) is written by the owner and is required as soon as the link holds a seal. The workspace's id is accepted while the link is seen by more than its owner, and is removed by the server when the link becomes private again.

replaceKey: true replaces all scope wraps and encrypted-entry seals atomically, for the owner only. expectedKeyWraps must match the complete previous scope map, every encrypted entry must be covered at its current version, and no new entry may be added. The owner's wrap, and the workspace wrap for a wider audience, are required. A stale state or partial replacement changes nothing. The slug and plaintext entries stay as they were; old fragment keys no longer open encrypted entries.

The server opens none of these. It checks that each one has the length its content gives it, that the caller holds the workspace's key and sees every entry, and that the link's owner sees them too. Links made by the server (request answers, sign-in shares) are refused.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 link, its records, and the seals written.
400 sealed_invalid (a malformed wrap, or a scope the link does not allow), sealed_link_content (not an encrypted entry the caller sees, or no owner's copy of the key) or sealed_record_unsupported.
403 sealed_key_missing, or an owner's key wrap sent by someone else.
404 No such link, or not one the caller may change.
409 sealed_version_conflict (the entry changed first), sealed_epoch_stale, or sealed_link_content when the entry is on too many links.
410 The link is revoked or expired.

POST /api/sealed/records/{id}/unseal

Store an encrypted entry in plain text again

Auth: Session

Experimental. The client decrypts the value and sends it back, signed by deviceSeq, a device on the caller's list.

For an encrypted file, the body goes in a multipart meta field with an empty value and the stored filename, and the decrypted file in blob. The device signs file: followed by the lowercase hex SHA-256 of that file, where it otherwise signs the value.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The saved entry.
400 sealed_invalid.
403 sealed_key_missing: no valid signature from a device on the list.
404 No such entry, or not one the caller may change.
409 sealed_version_conflict.

POST /api/sealed/sessions/revoke

End every other session on this account

Auth: Session

Experimental. Rotates the account's token key and answers with a new token for the caller. Every other session has to sign in again.

Responses

Status Meaning
200 token replaces the caller's session.
401 Not signed in.
403 An API key cannot do this.

POST /api/sealed/reset

Start over after losing every device and the recovery key

Auth: Session

Experimental. Clears the caller's device list and wrapped keys, and deletes encrypted entries in workspaces where nobody else holds the key. This cannot be undone. confirm must be delete my encrypted records.

Responses

Status Meaning
200 deleted counts the entries removed.
400 sealed_invalid: the confirmation is missing or wrong.