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. |
GET /api/sealed/records/{id}/links¶
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. |