keeporg/docs/PROTOCOL.md

KeepOrg HTTP API

Every /api/ endpoint takes and returns JSON and needs Authorization: Bearer <token>, except the login, device and invite endpoints. Errors carry {"code": "...", "error": "..."}; code is stable and meant to be matched on, error is for humans.

HTML is served at /web (sign in, list vaults, create one, change your password) and at /device, /invite/{token}, /oidc/login and /oidc/callback. /oidc/login with no parameters signs a browser in and ends in a session cookie; with ?code=<user code> it approves a waiting client instead and ends in a token that client polls for. The web pages use the same session tokens in a cookie that is HttpOnly, SameSite=Strict and Secure behind https, and every form carries a per-session CSRF token.

Authentication

Method	Path	Body	Answer
POST	/api/v1/auth/login	{username, password, totp, label}	{token, expires_at, user}; 401 totp_required when a second factor is enrolled and missing, 401 totp_invalid, 401 bad_credentials
POST	/api/v1/auth/logout	–	revokes the calling token
GET	/api/v1/auth/whoami	–	the account and its group memberships
POST	/api/v1/auth/password	{current_password, new_password, totp}	changes the account password; the current one is required, and the second factor when enrolled. Every other session of that account is revoked
POST	/api/v1/auth/totp/enroll	{password, totp}; totp only when a factor is already on	{secret, uri}; not active until confirmed. Without the password, 403 reauth_required; replacing an active factor needs its current code too
POST	/api/v1/auth/totp/confirm	{code}	{totp_enabled: true}
DELETE	/api/v1/auth/totp	{password, totp}	{totp_enabled: false}; 403 reauth_required, 403 bad_credentials, 403 totp_invalid
GET	/api/v1/auth/sessions	–	{sessions: [{id, label, browser, current, created_at, last_seen_at, expires_at}]}, the caller's own
DELETE	/api/v1/auth/sessions/{id}	–	signs that session out; 404 when it is not the caller's
DELETE	/api/v1/auth/sessions	–	{revoked: n}: every session of the caller but this one
POST	/api/v1/auth/device/start	{label, return_url}	{device_code, user_code, verification_url, interval, expires_in}; 400 when return_url is not a keeporg: URL
POST	/api/v1/auth/device/poll	{device_code}	202 {status: "pending"}, then 200 {token, ...} once; 410 expired

A device code is single use: the first successful poll consumes it.

Sign-in attempts are limited per client address and per account. Over the limit, /auth/login, /auth/device/start and the re-authenticating endpoints answer 429 throttled with Retry-After. A one-time code is accepted once; a second use is totp_invalid. Device labels are trimmed to 64 characters.

Endpoints about a database answer 404 not_found both for one that does not exist and for one the caller has no access to. A push to a merge vault whose KDBX header is malformed or demands more key derivation work than the server opens (internal/kdbx/limits.go) is 400 invalid_kdbx. A merge that cannot get a turn within 30 seconds is 503 busy.

A session id is a one-way digest of its token, never the token itself, so a list of sessions cannot be used to sign in as any of them. Failed re-authentication answers 403, not 401, so a client that drops its token on 401 does not sign itself out over a mistyped password. last_seen_at is refreshed at most every five minutes.

return_url is optional (server 0.9 and later). When it is given, the page that ends the approval, after a password or single sign-on, carries a "Return to KeepOrg" link to it. Only the keeporg: scheme is accepted, so the page cannot be made to send anybody elsewhere. It is for a client whose browser is a separate application, which is to say a phone; the client still learns of the approval by polling, and the link only brings the person back. Servers before 0.9 reject the unknown field with 400, so a client should retry without it.

Synchronization

Method	Path	Notes
GET	/api/v1/databases	{databases: [{id, name, perm, merge_strategy, version, sha256, size, updated_at, updated_by}]}
GET	/api/v1/databases/{id}/blob	bytes; ETag: "<version>", X-KeepOrg-SHA256; 204 when the database has no content yet; ?version=<n> reads a stored older version
PUT	/api/v1/databases/{id}/blob	body is the KDBX file. If-Match is required
GET	/api/v1/events	SSE, with the Authorization header like everything else. ?access_token= is still accepted here, and only here, for clients before 0.12; it puts the token in proxy logs. The stream ends once the session is revoked or the account disabled

PUT semantics

If-Match carries the version the edit was based on, or * to force.

Condition	Status	Body
If-Match missing	428 precondition_required	–
version matches, bytes differ	200	{version, sha256, unchanged: false}
version matches, bytes identical	200	{version, sha256, unchanged: true}
version stale, strategy is merge	200	{version, sha256, merged: true, merge_summary, based_on} — the two copies were folded together and the result stored as a new version
version stale, strategy is merge, but merging failed	409 merge_failed	{error, current_version, merge_strategy}; the stored vault is untouched
version stale, any other strategy	409 conflict	{current_version, merge_strategy}, plus ETag and X-KeepOrg-Strategy
If-Match: *, strategy is client-wins	200	the server copy is replaced
If-Match: *, any other strategy	409 force_not_allowed	–
read-only access	403 forbidden	–
no access	404 not_found	a database you cannot read does not exist to you
larger than max_db_size_mb	413 too_large	–

X-KeepOrg-SHA256 on a PUT is optional; when present it must match the body or the request is rejected with 400 checksum_mismatch.

After any accepted push, compare the sha256 in the answer with what you sent. If they differ the server stored something else — a merge — and the local copy must be replaced by a fresh GET.

Events

event: db-updated
data: {"type":"db-updated","database_id":"...","name":"Team","version":7,"sha256":"...","by":"alice"}

event: db-list-changed
data: {"type":"db-list-changed","database_id":"..."}

db-updated follows an accepted push; db-list-changed follows a grant, rename, strategy change or deletion. A comment line (: keepalive) arrives every 25 seconds. Reconnect on any error and reconcile fully; events are notifications, never state.

Vaults

A vault is a database the server created and can open. Creating one is the only way the server comes to hold a KDBX key, and the only strategy that needs one is merge.

Method	Path	Body	Needs
POST	/api/v1/vaults	{name, owner_group_id, merge_strategy, password}	group admin of the owner
POST	/api/v1/databases/{id}/key	{password} or {forget: true}	database admin

POST /api/v1/vaults builds an empty KDBX 4 database, encrypts it with password, stores it as version 1 and answers with the database view. The password must be at least 12 characters. For merge_strategy: "merge" (the default here) the password is kept, encrypted under the server's master key; for every other strategy it is used once and forgotten. A server with no master key refuses with 400.

POST /api/v1/databases/{id}/key stores the password of a database that already has content, after checking that it opens the stored version, which is how an uploaded database becomes mergeable. {"forget": true} removes it; that is refused while the strategy is still merge.

The wrapped key is never returned by any endpoint.

Administration

Permission needed is in the last column. "Group admin" means administering the group named or any group above it.

Method	Path	Body / query	Needs
GET	/api/v1/groups	–	any account; lists what you can see
POST	/api/v1/groups	{name, parent_id}	group admin of the parent; server admin for a root group
DELETE	/api/v1/groups/{id}	–	group admin; refuses while it has children, members or databases
POST	/api/v1/groups/{id}/members	{username or user_id, role}	group admin
DELETE	/api/v1/groups/{id}/members/{user}	–	group admin
POST	/api/v1/databases	{name, owner_group_id, merge_strategy}	group admin of the owner
PATCH	/api/v1/databases/{id}	{name?, merge_strategy?}	database admin
DELETE	/api/v1/databases/{id}	{password, totp?}	database admin, re-proving their own password; deletes every stored version
POST	/api/v1/grants	{group_id, database_id, perm}	database admin
DELETE	/api/v1/grants	?group_id=&database_id=	database admin
POST	/api/v1/invites	{group_id, role, ttl_hours, max_uses}	group admin
GET	/api/v1/invites	–	your own invites, and those of groups you administer
DELETE	/api/v1/invites/{token}	–	whoever may see it: its creator, an admin of its group, a server admin
GET	/api/v1/users	–	yourself, plus members of groups you administer
PATCH	/api/v1/users/{id}	{action}	server admin
GET	/healthz	–	unauthenticated liveness

merge_strategy is one of merge, server-wins, client-wins, manual. Switching to merge requires a stored key and is otherwise refused with 400. perm is one of read, write, admin. role is member or admin.

Deleting a database is the one call that asks for credentials again. A session token is enough to read and write a vault and not enough to destroy every version of it, so the body carries the caller's own account password, and totp as well when that account has a second factor enrolled — the server answers 401 totp_required when it is missing. An account that signs in only through an identity provider has no password to send and passes {"confirm_name": "<the database's exact name>"} instead.

An account action is one of disable, enable, promote, demote, clear-totp or delete. disable and delete also revoke every session that account holds. The three that would lock the caller out — disable, demote, delete — are refused on the caller's own account, because a server with no reachable administrator can only be repaired with keeporgd -reset-admin on the host.