管理 API の認証と移行

rc.44 のセッション、管理 PAT、モデル API キー、操作証明の違い

対象バージョンと API

本ページは 2026-10-15 に確認した new-api v1.0.0-rc.44 を対象とします。管理リクエストの送信先は https://api.beeaicloud.com です。ドキュメントのドメインは API の送信先ではありません。原生 /api/、BeeBridge /management-api/、/integration-api/ は異なる契約、セッション、エラー形式を使用します。

3 種類の認証情報

セッション access_token はパスワードまたは OAuth ログインによる短期 Bearer 認証情報で、セッションと PAT の管理に使用します。管理 PAT は nap_ で始まり、選択された管理権限だけを持ち、PAT 自体の作成や管理はできません。モデル API キー は /v1/ などの推論用です。同じ Authorization ヘッダーでも相互に代用できません。New-Api-User で別のアカウントを指定することはできず、本人情報はサーバーが認証情報から判断します。

ログインとパスワード暗号化

最初に GET /api/user/login/encryption-key を取得します。enabled=true の場合、ログインとパスワード検証の両方で password_encrypted と encryption_key_id を送信し、返された kid を使用します。Base64 の RSA-OAEP/SHA-256 暗号文に対応します。長いパスワードの v2 では、32 バイトの AES 鍵をラベル password-v2 の RSA-OAEP で包み、AES-256-GCM に 12 バイト nonce と AAD password-v2:{kid} を使用して、暗号文の末尾に 16 バイトのタグを付けます。形式は v2.{wrappedKeyBase64}.{nonceBase64}.{ciphertextAndTagBase64} です。暗号化が無効な場合だけ HTTPS 上で平文 password を使用します。

POST /api/user/login 後、data.require_verification を確認します。true なら data.methods に従い flow_token で /api/user/login/verify または Passkey 専用フローを完了してから、最終的な data.access_token を使用します。ログイン追加認証と /api/verify の操作証明は別です。更新は new_api_refresh Cookie と POST /api/user/auth/refresh、ログアウトは POST /api/user/auth/logout です。Cookie リクエストの Origin 検証を偽装して回避しないでください。

操作の追加認証

GET /api/verify/methods?scope=access_token.generate で available=true の方法を選びます。POST /api/verify に method、操作 scope、厳密な context を送信します。data.proof_token は同じ本人・セッションと同じ操作内容に対し X-Security-Proof で一回だけ消費できます。Passkey と OAuth には専用の対話フローが必要で、method の変更だけでは完了しません。

管理 PAT と権限

ログインセッションで /api/user/access_tokens/catalog を参照して必要な権限を選択します。profile:read は本人情報の参照だけで、キー管理、全使用量照会、ウォレット操作を意味しません。/api/user/access_tokens/scopes は名称辞書であり付与可能権限の一覧ではありません。PAT はアカウント状態、ロール、現在の認可にも制約されます。

失敗と再試行

HTTP 状態と success の両方を確認します。コードは code または data.code にあり、HTTP 200 でも業務上の失敗があります。400 SECURITY_CONTEXT_INVALID は context、401 は認証情報、403 はセッション要件と権限を確認します。429 では連続再試行を止めて待機します。作成・取消・変更の応答を失った場合は再送前に状態を照合します。ログには安全なコード、時刻、リクエスト ID のみを記録し、秘密情報は記録しません。

旧方式からの移行

旧 GET/POST /api/user/token は新規 PAT 発行には使用せず POST /api/user/access_tokens に移行します。GET /api/user/logout は POST /api/user/auth/logout、GET /api/verify/status は scope を指定した /api/verify/methods、GET /api/oauth/state は POST /api/oauth/state に置き換えます。証明は検証応答から取得します。既存の旧 PAT が移行期間に動作しても旧発行方式の継続を意味しません。期限は一覧の data.legacy.retire_at で確認します。現在の本番入口では原生の公開登録は閉鎖されています。

PAT →