トークン、設定、モジュール、アップデート、バックアップ API

認証とエラーは API の概要を見てください。このページの呼び出しの多くは、管理者または full トークンが必要です。

サインインとアカウント

スクリプトからはトークンを使ってください。ここにある呼び出しは、コンソールが使います。

呼び出し	アクション	内容
POST /v1/auth/login	なし（監査対象）	ボディは {"username": "admin", "password": "..."}。dbb_session Cookie を設定し、ユーザー、csrf_token、expires_at、can_change_password、language、can（コンソールの操作ごとの可否）を返す
GET /v1/auth/session	auth.session	現在のセッションについて、同じオブジェクトを返す
POST /v1/auth/logout	auth.logout	セッションを終了する。204
PUT /v1/auth/password	auth.password	ボディは {"current_password": "...", "new_password": "..."}。204。サインインプロバイダーがパスワードを管理している場合は 403 managed_elsewhere
POST /v1/auth/reset	auth.reset	クラスター全体の管理者パスワードをランダムな新しいものにし、すべてのセッションを終了する。ローカルソケット専用（db-branch admin reset-password）
GET /v1/auth/methods	なし	モジュールが追加するサインイン方法（シングルサインオンなど）を一覧する。ログインなしで使える
GET /v1/account/preferences	account.preference.read	{"language": "ja", "languages": ["en", "ja"]}
PUT /v1/account/preferences	account.preference.write	ボディは {"language": "en"}。空文字列はブラウザの設定に従う

トークン

GET /v1/tokens

アクション token.read。サービストークンを一覧します。秘密の値は再表示されません。

{ "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

アクション token.write。サービストークンを作ります。トークンのオブジェクトに秘密の値 token を加えて、201 で返します。秘密の値が表示されるのは、この応答だけです。

フィールド	型	意味
name	string、必須	ラベル
scope	string	branches（既定）または full
ttl	string	寿命（720h など）。省略すると期限なし

DELETE /v1/tokens/{id}

アクション token.write。サービストークンを失効させます。204 を返します。

個人トークン

GET /v1/account/tokens（account.token.read）、POST /v1/account/tokens（account.token.write、ボディは name と ttl）、DELETE /v1/account/tokens/{id}（account.token.write）は、上の呼び出しと同じ要領で、呼び出した本人のトークンだけを扱います。スコープは常に branches です。作成にはコンソールのセッションが必要で、スコープ付きトークンでの呼び出しは 403 forbidden です。

設定

クラスター全体の設定は、スコープごとにまとまっています。db-branch 自身の core と、設定を持つモジュールごとのスコープです。

GET /v1/settings

アクション setting.read。すべてのスコープと、その設定（現在の value と 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 は string、int、bool、duration、secret のいずれかです。

PUT /v1/settings/{scope}

アクション setting.write。スコープの値を変更し、上の形でスコープを返します。変更するキーだけを送ります。

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

未知のキーや型の合わない値は 400 invalid_request です。core のキーは、Web コンソールの Settings にまとめています。

モジュール

GET /v1/modules

アクション module.read。クラスターが必要とするモジュール、各ノードでの導入状況、パッケージリポジトリが提供するモジュールを一覧します。

{
  "items": [
    {
      "name": "auth", "version": "1.4.0", "wanted": true, "requires_license": true,
      "nodes": [ { "node": "node1", "loaded": "1.4.0", "current": true } ]
    }
  ],
  "available": { "auth": "<パッケージの説明>" }
}

モジュールが問題（たとえばライセンスについて）を報告しているノードには、problem の文字列が付きます。

POST /v1/modules

アクション module.install。全ノードでモジュールを有効にします。各ノードがパッケージをインストールします。ボディは {"name": "auth", "version": ""} で、version が空なら最新です。モジュールの仕様を返します。

DELETE /v1/modules/{name}

アクション module.remove。モジュールを無効にします。204 を返します。

モジュールが追加するページ、サインイン方法、API は /v1/ext/{module}/... で提供されます。これらのエンドポイントはモジュール自身が提供するもので、ここでは説明しません。読み取りにはアクション ext.<module>.read、書き込みには ext.<module>.write が必要です。?node=<name> を付けると、特定のノードに送れます。

ライセンス

有償モジュールは、最初の 30 日はキーなしで動き、それ以降はライセンスキーが必要です。

GET /v1/license

アクション license.read。{"configured": false}、または configured に加えて report（保存済みキーの顧客、モジュール、有効期限、state、有効にしたモジュール）を返します。トライアル中は、レポートに "trial": true が入ります。キー自体は返しません。

POST /v1/license/verify

アクション license.verify。キーを保存せずに検証します。ボディは {"key": "dbbl1...."} で、レポートを返します。

PUT /v1/license

アクション license.write。有効なキーを保存し、キーが対象とするモジュールを有効にします。ボディは同じで、レポートを返します。使えないキーは 422 invalid_license か 422 license_unusable、キーを検証できないビルドは 501 cannot_verify です。

アップデート

アップデートは、全ノードを新しいマイナーまたはパッチバージョンに上げます。フォロワーが先で、リーダーが最後です。

呼び出し	アクション	内容
GET /v1/updates	update.read	ノードとバージョン、新しいバージョンのあるパッケージ、latest_minor、現在の rollout
POST /v1/updates/check	update.check	パッケージリポジトリに新しいバージョンを問い合わせ、同じ内容を返す
POST /v1/updates	update.apply	ボディは {"target": "1.4.1"}。ロールアウトを始め、202 でロールアウトを返す
DELETE /v1/updates	update.apply	実行中のロールアウトを止める。204

ロールアウトには、status（running、done、failed、canceled）、order（アップデートするノードの順）、ノードごとの state（pending、updating、done、failed）があります。最初に失敗したノードで止まり、元には戻りません。実行中にもう一度始めると 409 rollout_running です。メジャーバージョンのアップデートは手作業で行います。

バックアップ

バックアップには、クラスターの状態（設定、トークン、モジュールとそのデータ、ルートユーザー、ランタイム、管理者パスワード）が入ります。Base のデータは入りません。ファイルには秘密が含まれます。

呼び出し	アクション	内容
GET /v1/backups	backup.read	{"node": "node1", "items": [{"name": "db-branch-node1-<time>.json.gz", "size": 20480, "taken_at": "..."}]}。?node=<name> で別のノード
POST /v1/backups	backup.create	このノード（または ?node=）で今すぐバックアップを取る。201 でファイルを返す
GET /v1/backups/{file}	backup.download	ファイルをダウンロードする（application/gzip）。ダウンロードは監査対象
POST /v1/backups/restore	backup.restore	ボディはバックアップファイル。ローカルソケット専用（db-branch backup restore <file>）。復元した内容の概要を返す

ルートユーザー

プロキシ（db-branch-proxysql）を動かしているノードでは、ルートユーザーは、既定の Branch につながるプロキシのログインです。プロキシがなければ、これらの呼び出しは 409 no_proxy です。

呼び出し	アクション	内容
GET /v1/route-users	route-user.read	{"name", "default_branch"} を一覧する。パスワードは返さない
PUT /v1/route-users/{name}	route-user.write	ボディは {"password": "...", "default_branch": "feature-x"}。ユーザーを作成または置き換える
DELETE /v1/route-users/{name}	route-user.delete	204

各 Branch には、Branch の名前と同じプロキシ用のユーザーもあります。Branch への接続を見てください。

MCP

/v1/mcp は、LLM エージェント向けの MCP エンドポイント（Streamable HTTP）です。同じ Bearer トークンを使い、各ツールの呼び出しは同じ権限チェックを通ります。上の REST のリソースには含まれません。設定方法は、Web コンソールの説明を見てください。