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}`, only when a factor is already on | `{secret, uri}`; not active until confirmed. Replacing an active factor without the password and current code is `403 reauth_required` |
| 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.

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. Accepts `?access_token=` because an event stream cannot always set headers |

### 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.