Skip to content
OpenVireoDeveloper
GitHub

API reference

Every route, its parameters and responses, from the OpenAPI description.

The HTTP API of openvireo-sync-server. It stores encrypted .kdbx files and never sees their contents. See docs/api.md for how the pieces fit together.

Which routes exist depends on SYNC_AUTH_MODE: standalone has the database and pairing routes, jwt the vault and internal routes, both all of them. /health and /events always exist. Routes the mode doesn’t have answer 404. The internal routes also need SYNC_INTERNAL_TOKEN to be set.

CORS: for origins in SYNC_ALLOWED_ORIGINS every route answers preflight with 204, allowing GET, HEAD, PUT, POST, DELETE and the headers Authorization, Content-Type, If-Match, If-None-Match, and responses expose ETag, X-Database-Revision, Last-Modified, Date.

Every response has Cache-Control: no-store.

The machine-readable description is openapi.yaml (OpenAPI 3.1.0); import it into an HTTP client or a code generator. The overview explains how the routes fit together.

Scheme
device A device token (self-hosted). From users add, devices add or a pairing claim.
access An account access token from the account server: EdDSA, aud containing SYNC_AUTH_AUDIENCE (default ov-sync), and a vlt claim mapping vault ids to read, write or manage, with an optional size quota q in bytes.
internal The SYNC_INTERNAL_TOKEN shared secret.

Liveness

Liveness check (getHealth)

Token: none

Status
200 The server is up (object)

A self-hosted user’s databases, with device tokens

List the user’s databases (listDatabases)

Token: device

Status
200 OK (object)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)

Download a database (getDatabase)

HEAD works the same and returns no body.

Token: device

Parameter In Type
id path string
If-None-Match (optional) header string * on uploads (create only), an ETag on downloads (304 when unchanged)
Status
200 The encrypted file (string (binary))
304 The ETag in If-None-Match is still current
401 Missing, invalid or expired token (Error)
404 Not found (Error)

Upload a database (putDatabase)

If-None-Match: * creates it (412 if it exists). If-Match: "<etag>" replaces exactly that version (412 if another device uploaded in the meantime). With neither header the upload creates the database, or gets 428 if it already exists. Sends a database event to the user’s other streams.

Token: device

Parameter In Type
id path string
If-Match (optional) header string
If-None-Match (optional) header string * on uploads (create only), an ETag on downloads (304 when unchanged)

Request body (application/octet-stream): The encrypted database, starting with the KDBX file signature

Status
200 200 when it replaced a version, 201 when it created the database or vault (Meta)
201 200 when it replaced a version, 201 when it created the database or vault (Meta)
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)
412 If-Match or If-None-Match didn’t hold; download, merge and try again (Error)
413 Over SYNC_MAX_DB_BYTES (no body), or on a vault over the token’s quota q for it: code quota_exceeded, and max (bytes) in the body (Error)
415 The body isn’t a KDBX file (Error)
428 The upload needs If-Match (update) or If-None-Match (create) (Error)

Delete a database and its history (deleteDatabase)

Token: device

Parameter In Type
id path string
If-Match (optional) header string
Status
204 Deleted
401 Missing, invalid or expired token (Error)
404 Not found (Error)
412 If-Match or If-None-Match didn’t hold; download, merge and try again (Error)

The current and kept versions, newest first (listDatabaseVersions)

Token: device

Parameter In Type
id path string
Status
200 OK (object)
401 Missing, invalid or expired token (Error)
404 Not found (Error)

GET /api/v1/databases/{id}/history/{revision}

Section titled “GET /api/v1/databases/{id}/history/{revision}”

Download one kept version (getDatabaseVersion)

Token: device

Parameter In Type
id path string
revision path integer
Status
200 The encrypted file (string (binary))
401 Missing, invalid or expired token (Error)
404 Not found (Error)

Pairing new devices

Create a pairing code for another device of the same user (createPairingCode)

Works once and for 10 minutes. A user has at most 5 codes waiting; a new one replaces the oldest.

Token: device

Status
201 Created (object)
401 Missing, invalid or expired token (Error)

Trade a pairing code for a device token (claimPairingCode)

Case, spaces and the dash in the code don’t matter. Wrong codes are limited to 10 per client address and 100 in all per 10 minutes; after that, claims get 429 with Retry-After.

Token: none

Request body (application/json)

Field Type
code string
deviceName string
Status
201 The new device and its token, shown only once (object)
400 Invalid id, JSON or body (Error)
429 Too many wrong codes (Error)

Account vaults, with access tokens from the account server

The vaults in the token’s vlt claim that exist (any role) (listVaults)

Token: access

Status
200 OK (object)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)

Download a vault (read) (getVault)

HEAD works the same and returns no body. A vault the token doesn’t list gets 403, whether it exists or not.

Token: access

Parameter In Type
vault path string (uuid)
If-None-Match (optional) header string * on uploads (create only), an ETag on downloads (304 when unchanged)
Status
200 The encrypted file (string (binary))
304 The ETag in If-None-Match is still current
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)
404 Not found (Error)

Create (manage) or update (write) a vault (putVault)

If-None-Match: * creates it and needs the manage role. If-Match: "<etag>" updates it and needs write. Without either header the upload always gets 428. Sends a vault event to the streams whose token lists the vault.

Token: access

Parameter In Type
vault path string (uuid)
If-Match (optional) header string
If-None-Match (optional) header string * on uploads (create only), an ETag on downloads (304 when unchanged)

Request body (application/octet-stream): The encrypted database, starting with the KDBX file signature

Status
200 200 when it replaced a version, 201 when it created the database or vault (Meta)
201 200 when it replaced a version, 201 when it created the database or vault (Meta)
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)
412 If-Match or If-None-Match didn’t hold; download, merge and try again (Error)
413 Over SYNC_MAX_DB_BYTES (no body), or on a vault over the token’s quota q for it: code quota_exceeded, and max (bytes) in the body (Error)
415 The body isn’t a KDBX file (Error)
428 The upload needs If-Match (update) or If-None-Match (create) (Error)

Delete a vault and its history (manage) (deleteVault)

Token: access

Parameter In Type
vault path string (uuid)
If-Match (optional) header string
Status
204 Deleted; the vault’s streams get a vault event with deleted true
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)
404 Not found (Error)
412 If-Match or If-None-Match didn’t hold; download, merge and try again (Error)

The current and kept versions, newest first (read) (listVaultVersions)

Token: access

Parameter In Type
vault path string (uuid)
Status
200 OK (object)
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)
404 Not found (Error)

GET /api/v1/vaults/{vault}/history/{revision}

Section titled “GET /api/v1/vaults/{vault}/history/{revision}”

Download one kept version (read) (getVaultVersion)

Token: access

Parameter In Type
vault path string (uuid)
revision path integer
Status
200 The encrypted file (string (binary))
401 Missing, invalid or expired token (Error)
403 The token doesn’t grant this, or is the wrong kind of token for the route (Error)
404 Not found (Error)

Change notifications (server-sent events)

Change notifications as server-sent events (streamEvents)

Starts with retry: 5000; a : ping comment every 25 seconds keeps it open.

With a device token: event: database, data {"id", "etag", "revision"} or {"id", "deleted": true}, for every change to one of the user’s databases.

With an access token: event: vault (same data, for the vaults in the token) and event: access, data {"vault": uuid|null, "change": "granted"|"revoked"|"rotating"|"rotated"|"org"}, when the account server reports an access change for the token’s subject. The stream ends once the token’s exp has passed; the client reconnects with a fresh token, and also after any access event.

Token: device or access

Status
200 The stream (string)
401 Missing, invalid or expired token (Error)

Called by the account server only

Push an access event to the open streams of some subjects (notifyAccess)

Delivery is best effort. With Postgres, the event reaches streams on every instance.

Token: internal

Request body (application/json)

Field Type
subjects array of Principal
event "access"
data object
Status
204 Sent
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)

Delete a vault and its history when no client does, e.g. an expired recovery archive (deleteVaultInternal)

Token: internal

Parameter In Type
vault path string (uuid)
Status
204 Deleted; the vault’s streams get a vault event with deleted true
400 Invalid id, JSON or body (Error)
401 Missing, invalid or expired token (Error)
404 Not found (Error)
Field Type
id string The database id or vault UUID
revision integer
etag string The quoted SHA-256 of the file
size integer Bytes
updatedAt string (date-time)

string, matching ^(user|sa):[0-9a-f-]{36}$

Field Type
error string A message for people
code (optional) invalid_request, unauthorized, forbidden, not_found, conflict, precondition_failed, precondition_required, quota_exceeded, rate_limited, internal_error Only on the vault and internal routes, and on /events when access tokens are accepted