Tokens, settings, modules, updates and backups API

See the API overview for authentication and errors. Most calls on this page need an admin or a full token.

Sign-in and account

Scripts should use tokens. These calls serve the console.

Call	Action	What it does
POST /v1/auth/login	none (audited)	Body {"username": "admin", "password": "..."}. Sets the dbb_session cookie and returns the user, csrf_token, expires_at, can_change_password, language and can (a map of which console actions the user may do)
GET /v1/auth/session	auth.session	Returns the same object for the current session
POST /v1/auth/logout	auth.logout	Ends the session. 204
PUT /v1/auth/password	auth.password	Body {"current_password": "...", "new_password": "..."}. 204. 403 managed_elsewhere if a sign-in provider owns the password
POST /v1/auth/reset	auth.reset	Sets a new random admin password for the cluster and ends every session. Local socket only (db-branch admin reset-password)
GET /v1/auth/methods	none	Lists extra sign-in methods that modules provide (for example single sign-on). Works without a login
GET /v1/account/preferences	account.preference.read	{"language": "ja", "languages": ["en", "ja"]}
PUT /v1/account/preferences	account.preference.write	Body {"language": "en"}; an empty string follows the browser

Tokens

GET /v1/tokens

Action token.read. Lists service tokens. The secret is never shown again.

{ "items": [ { "id": "...", "name": "ci-deploy", "scope": "branches", "created_at": "2026-11-09T12:00:00Z", "expires_at": "2026-12-09T12:00:00Z" } ], "next_cursor": null }

POST /v1/tokens

Action token.write. Creates a service token. Answers 201 with the token object plus token, the secret. It is shown only in this response.

Field	Type	Meaning
name	string, required	A label
scope	string	branches (default) or full
ttl	string	Lifetime such as 720h. Omit for no expiry

DELETE /v1/tokens/{id}

Action token.write. Revokes a service token. 204.

Personal tokens

GET /v1/account/tokens (account.token.read), POST /v1/account/tokens (account.token.write, body name and ttl) and DELETE /v1/account/tokens/{id} (account.token.write) work like the calls above but only on the caller’s own tokens, which always have scope branches. Creating one requires a console session; a call made with a scoped token returns 403 forbidden.

Settings

Cluster-wide settings are grouped in scopes: core for db-branch itself, and one scope for each module that has settings.

GET /v1/settings

Action setting.read. Lists every scope with its settings, their current value and default.

{
  "items": [
    {
      "scope": "core",
      "title": "db-branch",
      "settings": [
        { "key": "branch.default_ttl", "label": "Default TTL", "help": "Expiry for branches created without one, e.g. 72h. Empty: no expiry.", "type": "duration", "default": "", "value": "72h" }
      ]
    }
  ],
  "next_cursor": null
}

type is string, int, bool, duration or secret.

PUT /v1/settings/{scope}

Action setting.write. Changes values in a scope and returns the scope as above. Send only the keys to change.

{ "values": { "branch.default_ttl": "72h", "backup.interval": "12h" } }

An unknown key or a value of the wrong type returns 400 invalid_request. The core keys are listed under Settings in the web console guide.

Modules

GET /v1/modules

Action module.read. Lists the modules the cluster wants, how far each node has come, and what the package repositories offer.

{
  "items": [
    {
      "name": "auth", "version": "1.4.0", "wanted": true, "requires_license": true,
      "nodes": [ { "node": "node1", "loaded": "1.4.0", "current": true } ]
    }
  ],
  "available": { "auth": "<description from the package>" }
}

A node whose module reports a problem (for example about the licence) has a problem string.

POST /v1/modules

Action module.install. Turns a module on for every node; the nodes install the package. Body {"name": "auth", "version": ""}; an empty version takes the latest. Returns the module spec.

DELETE /v1/modules/{name}

Action module.remove. Turns a module off. 204.

Pages, sign-in methods and APIs that modules add are served under /v1/ext/{module}/.... Those endpoints are provided by the modules themselves and are not described here. Reads need the action ext.<module>.read and writes ext.<module>.write. Add ?node=<name> to send a call to a specific node.

License

Paid modules work for 30 days without a key, then only under a licence key.

GET /v1/license

Action license.read. Returns {"configured": false}, or configured with a report (the saved key’s customer, modules, expiry, state and the modules it enabled). During the trial the report has "trial": true. The key itself is never returned.

POST /v1/license/verify

Action license.verify. Checks a key without saving it. Body {"key": "dbbl1...."}. Returns the report.

PUT /v1/license

Action license.write. Saves a valid key and turns on the modules it covers. Body as above. Returns the report. An unusable key returns 422 invalid_license or 422 license_unusable; a build that cannot check keys returns 501 cannot_verify.

Updates

Updates move every node to a newer minor or patch version, followers first and the leader last.

Call	Action	What it does
GET /v1/updates	update.read	Nodes with their versions, packages with the newer versions on offer, latest_minor, and the current rollout
POST /v1/updates/check	update.check	Asks the package repository for newer versions and returns the same view
POST /v1/updates	update.apply	Body {"target": "1.4.1"}. Starts a rollout. 202 with the rollout
DELETE /v1/updates	update.apply	Stops the running rollout. 204

A rollout has status (running, done, failed, canceled), order (the nodes in update order) and per-node state (pending, updating, done, failed). It stops at the first failed node and does not roll back. Starting one while another runs returns 409 rollout_running. Major versions are updated by hand.

Backups

A backup holds the cluster state (settings, tokens, modules and their data, route users, runtimes, the admin password), not the data of bases. The files contain secrets.

Call	Action	What it does
GET /v1/backups	backup.read	{"node": "node1", "items": [{"name": "db-branch-node1-<time>.json.gz", "size": 20480, "taken_at": "..."}]}. Add ?node=<name> for another node
POST /v1/backups	backup.create	Takes a backup on this node (or ?node=) now. 201 with the file
GET /v1/backups/{file}	backup.download	Downloads the file (application/gzip). Each download is audited
POST /v1/backups/restore	backup.restore	Body is the backup file. Local socket only (db-branch backup restore <file>); returns a summary of what was restored

Route users

On nodes that run the proxy (db-branch-proxysql), a route user is a proxy login that opens a default branch. Without the proxy these calls return 409 no_proxy.

Call	Action	What it does
GET /v1/route-users	route-user.read	Lists {"name", "default_branch"}. Passwords are never returned
PUT /v1/route-users/{name}	route-user.write	Body {"password": "...", "default_branch": "feature-x"}. Creates or replaces the user
DELETE /v1/route-users/{name}	route-user.delete	204

Each branch also gets a proxy user named after the branch; see Connecting to a branch.

MCP

/v1/mcp is the MCP endpoint (Streamable HTTP) for LLM agents. It takes the same bearer tokens and runs each tool through the same checks. It is not part of the REST resources above; see the MCP setup in the web console guide.