HTTP API

Generated from the route registrations in server/internal/syncapi/ and server/internal/web/. Do not edit.

The server has two kinds of routes. The sync API under /api/v1/ is for devices and scoped keys. It uses a bearer token, no cookies and no CSRF token. The web app routes are for the browser. They use the session cookie.

The authentication column shows what a route needs:

None: no login. A few of these check a one-time token or a code in the request.
Bearer token: a device token or a scoped key in the Authorization header.
Bearer token, admin access: the same, and the session or key has admin access.
Session: the session cookie of a logged-in user.
Session, unlocked E2E tab: the session cookie, and the browser tab has unlocked its end-to-end keys.

Sync API

These routes are under /api/v1/.

/api/v1/account

Method	Path	Authentication	Purpose
GET	`/api/v1/account/keys`	Bearer token	Gets the encrypted user keys and the key derivation parameters of the caller.
GET	`/api/v1/account/rotation`	Bearer token	Gets the plan to rotate the user keys.
POST	`/api/v1/account/rotation`	Bearer token	Applies a rotation of the user keys.

/api/v1/admin

Method	Path	Authentication	Purpose
GET	`/api/v1/admin/invitations`	Bearer token, admin access	Lists the open invitations. Needs admin access.
POST	`/api/v1/admin/invitations`	Bearer token, admin access	Makes an invitation and returns its link once. Needs admin access.
DELETE	`/api/v1/admin/invitations/{id}`	Bearer token, admin access	Revokes an open invitation. Needs admin access.
GET	`/api/v1/admin/registration`	Bearer token, admin access	Gets who can register: closed, invite or open. Needs admin access.
PUT	`/api/v1/admin/registration`	Bearer token, admin access	Sets who can register. Needs admin access.
GET	`/api/v1/admin/users`	Bearer token, admin access	Lists the users of the server. Needs admin access.
POST	`/api/v1/admin/users/{id}/cancel-delete`	Bearer token, admin access	Cancels a deletion that is in its grace period. Needs admin access.
POST	`/api/v1/admin/users/{id}/delete`	Bearer token, admin access	Starts the deletion of a user. The data stays until a grace period ends. Needs admin access.
POST	`/api/v1/admin/users/{id}/disable`	Bearer token, admin access	Disables a user and revokes the sessions, devices and keys of the user. Needs admin access.
POST	`/api/v1/admin/users/{id}/enable`	Bearer token, admin access	Enables a disabled user. Needs admin access.
POST	`/api/v1/admin/users/{id}/role`	Bearer token, admin access	Sets the role of a user. Needs admin access.

/api/v1/approvals

Method	Path	Authentication	Purpose
GET	`/api/v1/approvals/pending`	Bearer token	Lists the per-use approvals that wait for a decision.
POST	`/api/v1/approvals/{id}/decision`	Bearer token	Approves or denies a per-use approval.

/api/v1/auth

Method	Path	Authentication	Purpose
POST	`/api/v1/auth/device`	None	Starts a device-code login. Returns a device code, a user code and the address to approve in the browser.
POST	`/api/v1/auth/refresh`	None	Trades a refresh token for a new access token and a new refresh token.
POST	`/api/v1/auth/token`	None	Polls a device-code login or trades a code for tokens. Answers authorization_pending until the user approves.

/api/v1/contacts

Method	Path	Authentication	Purpose
GET	`/api/v1/contacts`	Bearer token	Lists the contacts of the caller (users with a pinned key).
PUT	`/api/v1/contacts/{user}`	Bearer token	Pins the key of a contact.

/api/v1/devices

Method	Path	Authentication	Purpose
POST	`/api/v1/devices/login`	None	Logs in with the auth key and makes a device. Returns a bearer token once.
DELETE	`/api/v1/devices/self`	Bearer token	Revokes the device of the calling token (logout).

/api/v1/events

Method	Path	Authentication	Purpose
GET	`/api/v1/events`	Bearer token	Server-sent events for devices. Tells a device that a space changed. It never sends data.

/api/v1/grants

Method	Path	Authentication	Purpose
GET	`/api/v1/grants`	Bearer token	Lists the grant rows of the calling session or key.

/api/v1/keys

Method	Path	Authentication	Purpose
GET	`/api/v1/keys`	Bearer token, admin access	Lists scoped keys. Needs admin access.
POST	`/api/v1/keys`	Bearer token, admin access	Makes a scoped key. The body has the record that the client made and signed. Needs admin access.
GET	`/api/v1/keys/self`	Bearer token	Gets the record of the scoped key of the calling token.
DELETE	`/api/v1/keys/{id}`	Bearer token, admin access	Revokes a scoped key. The body may have a signed revocation record. Needs admin access.
POST	`/api/v1/keys/{id}/revocation`	Bearer token, admin access	Stores the signed revocation record of a key that is already revoked. Needs admin access.

/api/v1/pair

Method	Path	Authentication	Purpose
POST	`/api/v1/pair`	Session	Makes a pairing offer for the QR code of the web app. Uses the web session.
POST	`/api/v1/pair/status`	Session	Tells if a pairing offer has been used. Uses the web session.

/api/v1/peers

Method	Path	Authentication	Purpose
GET	`/api/v1/peers`	Bearer token	Lists the other devices of the user for peer sync, with their public keys and endpoints.
PUT	`/api/v1/peers/self`	Bearer token	Publishes the peer key and the endpoints of this device.
POST	`/api/v1/peers/{id}/punch`	Bearer token	Asks the server to tell two devices to open a direct connection at the same time.

/api/v1/prelogin

Method	Path	Authentication	Purpose
POST	`/api/v1/prelogin`	None	Gets the key derivation parameters of a user, so the client can derive its keys before it logs in.

/api/v1/sessions

Method	Path	Authentication	Purpose
GET	`/api/v1/sessions`	Bearer token, admin access	Lists the device-code sessions. Needs admin access.
DELETE	`/api/v1/sessions/{id}`	Bearer token, admin access	Ends a device-code session. Needs admin access.

/api/v1/spaces

Method	Path	Authentication	Purpose
GET	`/api/v1/spaces`	Bearer token	Lists the spaces and memberships of the caller.
POST	`/api/v1/spaces`	Bearer token	Makes a shared space. The body is the signed first entry of the membership log.
GET	`/api/v1/spaces/{id}/certs`	Bearer token	Gets the certs of scoped keys and their revocation records, to check the signers of ops.
GET	`/api/v1/spaces/{id}/checkpoints`	Bearer token	Reads the signed checkpoints of the end-to-end roots that the caller can see.
POST	`/api/v1/spaces/{id}/checkpoints`	Bearer token	Stores a signed checkpoint of an end-to-end root.
GET	`/api/v1/spaces/{id}/folder-keys`	Bearer token	Gets the folder keys that are sealed to the caller.
POST	`/api/v1/spaces/{id}/folder-keys`	Bearer token	Stores folder keys that are sealed to the members of a shared space.
POST	`/api/v1/spaces/{id}/have`	Bearer token	Tells which of a list of op IDs the server has. Peer sync uses it.
GET	`/api/v1/spaces/{id}/items/{item}/fields`	Bearer token	Lists the fields of a server-readable item, with no values.
GET	`/api/v1/spaces/{id}/log`	Bearer token	Reads the signed membership log of a shared space.
POST	`/api/v1/spaces/{id}/log`	Bearer token	Adds one signed entry to the membership log of a shared space.
GET	`/api/v1/spaces/{id}/ops`	Bearer token	Reads ops of a space after a cursor.
POST	`/api/v1/spaces/{id}/purge`	Bearer token	Purges an entity for good, with a signed purge record for an end-to-end entity.
GET	`/api/v1/spaces/{id}/purges`	Bearer token	Reads the purge records of a space after a cursor.
POST	`/api/v1/spaces/{id}/push`	Bearer token	Pushes groups of ops. Each group succeeds or fails as one unit.
POST	`/api/v1/spaces/{id}/reads`	Bearer token	Reads secret values of server-readable items for a scoped key or a session. Starts an approval if the item needs one.
GET	`/api/v1/spaces/{id}/rekey`	Bearer token	Gets the data that an admin needs to rekey a shared space.

/api/v1/teams

Method	Path	Authentication	Purpose
GET	`/api/v1/teams`	Bearer token	Lists the teams of the caller.
POST	`/api/v1/teams`	Bearer token	Makes a team. The body is the signed first entry of the team log.
GET	`/api/v1/teams/{id}/keys`	Bearer token	Gets the team keys that are sealed to the caller.
GET	`/api/v1/teams/{id}/log`	Bearer token	Reads the signed log of a team.
POST	`/api/v1/teams/{id}/log`	Bearer token	Adds one signed entry to the log of a team.

/api/v1/users

Method	Path	Authentication	Purpose
GET	`/api/v1/users/lookup`	Bearer token	Finds a user by name and gets the public keys. Used to add a member to a shared space.

Web app routes

The browser uses these routes. Pages return HTML. Routes under /api/ return JSON.

(root)

Method	Path	Authentication	Purpose
GET	`/{$}`	Session	The vault: the main page of the web app.

/api/devices

Method	Path	Authentication	Purpose
GET	`/api/devices`	Session	Gives the names of the devices of the user by device ID.

/api/e2e

Method	Path	Authentication	Purpose
GET	`/api/e2e/certs`	Session	Gets the certs of scoped keys and their revocation records.
POST	`/api/e2e/checkpoints`	Session, unlocked E2E tab	Stores a signed checkpoint.
GET	`/api/e2e/contacts`	Session, unlocked E2E tab	Lists the contacts of the user.
PUT	`/api/e2e/contacts/{user}`	Session, unlocked E2E tab	Pins the key of a contact.
POST	`/api/e2e/folders`	Session, unlocked E2E tab	Makes an end-to-end root with its signed bundle.
POST	`/api/e2e/move`	Session, unlocked E2E tab	Moves an entity into or out of an end-to-end scope.
POST	`/api/e2e/ops`	Session, unlocked E2E tab	Appends signed ops to an end-to-end scope.
POST	`/api/e2e/orphans/{rootID}/purge`	Session, unlocked E2E tab	Purges an end-to-end root that no member can open any more.
POST	`/api/e2e/purge`	Session, unlocked E2E tab	Purges an entity in an end-to-end scope with a signed purge record.
GET	`/api/e2e/rotation`	Session, unlocked E2E tab	Gets the plan to rotate the user keys.
POST	`/api/e2e/rotation`	Session, unlocked E2E tab	Applies a rotation of the user keys.
GET	`/api/e2e/scopes`	Session, unlocked E2E tab	Lists the end-to-end roots of the user.
GET	`/api/e2e/scopes/{rootID}`	Session, unlocked E2E tab	Gets the ops and the folder key of one end-to-end root.
GET	`/api/e2e/spaces`	Session, unlocked E2E tab	Lists the shared spaces of the user for the sidebar.
POST	`/api/e2e/spaces`	Session, unlocked E2E tab	Makes a shared space from the browser.
POST	`/api/e2e/spaces/{id}/folder-keys`	Session, unlocked E2E tab	Stores folder keys sealed to the members of a shared space.
GET	`/api/e2e/spaces/{id}/log`	Session, unlocked E2E tab	Reads the membership log of a shared space.
POST	`/api/e2e/spaces/{id}/log`	Session, unlocked E2E tab	Adds one signed entry to the membership log.
GET	`/api/e2e/spaces/{id}/rekey`	Session, unlocked E2E tab	Gets the data to rekey a shared space.
DELETE	`/api/e2e/tab-key`	Session	Deletes the wrapped key of the tab. This locks the tab.
GET	`/api/e2e/tab-key`	Session	Gets the wrapped key of an unlocked browser tab.
POST	`/api/e2e/tab-key`	Session	Stores the wrapped key of an unlocked browser tab.
POST	`/api/e2e/tab-key/touch`	Session	Marks the tab key as used, so the idle timer restarts.
GET	`/api/e2e/teams`	Session, unlocked E2E tab	Lists the teams of the user.
POST	`/api/e2e/teams`	Session, unlocked E2E tab	Makes a team.
GET	`/api/e2e/teams/{id}/keys`	Session, unlocked E2E tab	Gets the team keys that are sealed to the user.
GET	`/api/e2e/teams/{id}/log`	Session, unlocked E2E tab	Reads the log of a team.
POST	`/api/e2e/teams/{id}/log`	Session, unlocked E2E tab	Adds one signed entry to the log of a team.
GET	`/api/e2e/unlock`	Session, unlocked E2E tab	Gets the data that the browser needs to unlock the end-to-end keys.
GET	`/api/e2e/users/lookup`	Session, unlocked E2E tab	Finds a user by name to add as a member.

/api/import

Method	Path	Authentication	Purpose
POST	`/api/import/plain`	Session	Imports items into a plain folder.

/api/login

Method	Path	Authentication	Purpose
POST	`/api/login`	None	Logs in to the web app and starts a session.

/api/prelogin

Method	Path	Authentication	Purpose
POST	`/api/prelogin`	None	Gets the key derivation parameters of a user for the web login.

/api/recover

Method	Path	Authentication	Purpose
POST	`/api/recover/finish`	None	Finishes a recovery and sets a new master password.
POST	`/api/recover/id`	None	Looks up the account for a recovery by the recovery code.
POST	`/api/recover/start`	None	Starts a recovery with the recovery code.

/api/recovery-kit

Method	Path	Authentication	Purpose
POST	`/api/recovery-kit`	Session	Stores the sealed recovery kit of the user.

/api/register

Method	Path	Authentication	Purpose
POST	`/api/register`	None	Makes an account. Works for the first user, with an invitation, or when registration is open.

/api/reset

Method	Path	Authentication	Purpose
POST	`/api/reset/check`	None	Checks the one-time link of an operator password reset.
POST	`/api/reset/finish`	None	Finishes an operator password reset: sets a new master password and makes new user keys.

/api/totp

Method	Path	Authentication	Purpose
POST	`/api/totp/confirm`	Session	Turns TOTP on after the user enters a valid code.
POST	`/api/totp/disable`	Session	Turns TOTP off after the user enters a valid code.
POST	`/api/totp/start`	Session	Starts the set-up of TOTP and returns the secret.

/app

Method	Path	Authentication	Purpose
GET	`/app`	None	The page with the steps to install the app and open it with this server.

/approvals

Method	Path	Authentication	Purpose
GET	`/approvals/pending`	Session	The dialog of the oldest pending per-use approval. Returns 204 if there is none.
POST	`/approvals/{id}/approve`	Session	Approves a per-use approval. For an end-to-end item, the body has the sealed just-in-time grants.
POST	`/approvals/{id}/deny`	Session	Denies a per-use approval.

/approve

Method	Path	Authentication	Purpose
GET	`/approve`	None	The page to approve a device-code login. Shows the code and the access that the device asks for.
POST	`/approve`	None	Records the decision about a device-code login.

/events

Method	Path	Authentication	Purpose
GET	`/events`	Session	Server-sent events for the web app. Tells the page that a space changed.

/login

Method	Path	Authentication	Purpose
GET	`/login`	None	The login page.

/logout

Method	Path	Authentication	Purpose
POST	`/logout`	None	Ends the web session.

/pair

Method	Path	Authentication	Purpose
GET	`/pair`	None	The page that hands a pairing offer to the app.

/recover

Method	Path	Authentication	Purpose
GET	`/recover`	None	The page to recover an account with the recovery code.

/register

Method	Path	Authentication	Purpose
GET	`/register`	None	The page to make an account.

/reset

Method	Path	Authentication	Purpose
GET	`/reset`	None	The page for the one-time link of an operator password reset.

/settings

Method	Path	Authentication	Purpose
GET	`/settings/appearance`	Session	The appearance settings.
GET	`/settings/audit`	Session	The audit log of the user.
GET	`/settings/devices`	Session	Lists the devices and sessions of the user.
POST	`/settings/devices/remove`	Session	Removes one device or one other session.
GET	`/settings/import`	Session	The page to import a file from another password manager.
GET	`/settings/keys`	Session	Lists the scoped keys and has the form to make one.
POST	`/settings/keys`	Session	Stores a scoped key that the page made.
POST	`/settings/keys/revocation`	Session	Stores the signed revocation record of a key.
POST	`/settings/keys/revoke`	Session	Revokes a scoped key.
GET	`/settings/organisation`	Session	The organisation settings: users, invitations and registration. Needs admin access.
POST	`/settings/organisation/invite`	Session	Makes an invitation. The answer shows the link and a QR code once.
POST	`/settings/organisation/invite/revoke`	Session	Revokes an invitation.
POST	`/settings/organisation/registration`	Session	Sets who can register.
POST	`/settings/organisation/users/{action}`	Session	Runs a user action of the organisation page, such as disable or enable.
GET	`/settings/security`	Session	The security settings: password, TOTP, recovery kit.

/static

Method	Path	Authentication	Purpose
GET	`/static/`	None	Static files of the web app (scripts, styles, fonts, images).

/theme

Method	Path	Authentication	Purpose
POST	`/theme`	None	Stores the theme choice.

/vault

Method	Path	Authentication	Purpose
GET	`/vault/e2e/purge`	Session	The dialog to purge an item or folder in an end-to-end folder.
GET	`/vault/empty`	Session	The empty state of the vault page.
POST	`/vault/entities/{id}/delete`	Session	Moves an item or folder to the trash.
GET	`/vault/entities/{id}/purge`	Session	The confirm dialog to purge an entity for good.
POST	`/vault/entities/{id}/purge`	Session	Purges an entity for good.
POST	`/vault/entities/{id}/restore`	Session	Restores an item or folder from the trash.
GET	`/vault/field-row`	Session	A new field row for the item form.
POST	`/vault/folders`	Session	Makes a plain folder.
GET	`/vault/folders/new`	Session	The dialog for a new folder, with the choice of the type.
POST	`/vault/folders/{id}/move`	Session	Moves a folder.
POST	`/vault/folders/{id}/rename`	Session	Renames a folder.
GET	`/vault/generate`	Session	Generates a password.
POST	`/vault/items`	Session	Makes an item.
GET	`/vault/items/{id}`	Session	The detail of an item. Secrets stay hidden.
POST	`/vault/items/{id}`	Session	Saves the changes of an item.
POST	`/vault/items/{id}/conflicts/{fid}/dismiss`	Session	Hides the note about a field that changed on two devices.
GET	`/vault/items/{id}/edit`	Session	The edit form of an item.
POST	`/vault/items/{id}/fields/{fid}/restore`	Session	Restores an older value of a field.
GET	`/vault/items/{id}/fields/{fid}/totp`	Session	The current TOTP code of a field.
GET	`/vault/items/{id}/fields/{fid}/value`	Session	One field value as plain text, for reveal and copy.
GET	`/vault/items/{id}/history`	Session	The history of an item.
GET	`/vault/items/{id}/move`	Session	The dialog to move an item.
POST	`/vault/items/{id}/move`	Session	Moves an item between plain folders.
GET	`/vault/items/{id}/plain`	Session	The plain item as JSON, so the browser can encrypt it for an end-to-end folder.
GET	`/vault/new`	Session	The form for a new item.
GET	`/vault/search`	Session	Searches the items by name, user name and URL.

Configuration Error codes