Management Authentication

範圍矩陣

API 金鑰管理範圍和存取權杖範圍是不同的詞彙。MCP 工具範圍是第三種詞彙，使用 scopeMatches 檢查，而不是下表中任一函數。並排比較：三個範圍命名空間。

存取權杖範圍 (`oma_live_…`)

範圍	典型操作
`read`	權杖允許查看的列表/狀態 GET 請求
`write`	管理員權限以下的變更 (建立/更新/刪除)
`admin`	完整的遠端 CLI / 連線權杖 (密碼引導預設在此)

具有 read 權限的權杖無法呼叫 write 路由。執行時訊息格式：存取權杖範圍 '<have>' 不足；需要 '<need>'。

API 金鑰管理範圍

範圍	意義
(無)	僅限推論。管理路由返回 403。
`manage`	管理 API (與 `requireManagementAuth` API 金鑰分支相同的閘道)
`admin`	也滿足 `hasManageScope` (被視為具備管理能力)

在 API 金鑰 / API 管理器使用者介面中啟用金鑰上的 manage。除非您刻意授予該範圍，否則不要將聊天客戶端金鑰重複用於自動化。

如何建立和撤銷

儀表板 JWT 會話

開啟 /login，使用管理密碼登入（首次啟動時為 INITIAL_PASSWORD）。
Cookie auth_token 是 HttpOnly。瀏覽器儀表板會自動使用它。
透過 /api/auth/logout 登出。沒有可複製的長期密鑰。

CLI 機器 ID 令牌

在與伺服器相同的主機上執行 omniroute（迴路）。
CLI 會在 ~/.omniroute/ 下引導一個機器 ID 令牌（chmod 600）。
這在另一台機器上不起作用。請使用存取令牌進行遠端 CLI。

範圍存取令牌 (`oma_live_…`)

儀表板：設定 → 存取令牌 → 建立（名稱 + 範圍）。密鑰只顯示一次。
或 CLI：omniroute connect <host>（密碼 → 令牌）。請參閱遠端模式。
標頭：Authorization: Bearer oma_live_…
從相同的存取令牌頁面撤銷（或刪除 CLI 上下文）。
伺服器只儲存雜湊。請像對待密碼一樣對待明文。

管理範圍 API 金鑰

儀表板：API 管理器 / API 金鑰 → 建立或編輯金鑰 → 啟用 manage（或 admin）。
標頭：Authorization: Bearer sk-…（金鑰的實際前綴）。
在相同的 UI 中撤銷或移除 manage。
對於非 CLI 的自動化，請使用最小權限：對於僅 GET 的任務，請優先使用 read 存取令牌；僅當呼叫者也必須使用 /v1 和管理時，才在 API 金鑰上使用 manage。

標頭格式

Authorization: Bearer oma_live_<secret>
Authorization: Bearer sk-<secret>
Cookie: auth_token=<dashboard-jwt>

請勿將管理憑證放在 URL 路徑或查詢字串中。管理驗證僅限於標頭/Cookie。

複製貼上範例

唯讀（列出提供者）。使用 read 存取令牌：

curl -sS "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<read-token>"

修改（建立提供者連線）。使用 write/admin 存取令牌或管理範圍 API 金鑰：

curl -sS -X POST "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<write-or-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","apiKey":"<upstream-key>"}'

推斷（非管理）。普通 API 金鑰，無需 manage：

curl -sS "$OMNIROUTE_URL/v1/models" \
  -H "Authorization: Bearer sk-<inference-key>"

目前執行時錯誤（不回顯密鑰）

情況	典型狀態	訊息（已淨化）
無憑證	401	`Authentication required`
無效/過期 `oma_live_…`	401	`Invalid or expired access token`
有效 API 金鑰但無 `manage`/`admin`	403	`API key lacks 'manage' scope. Enable it in the API Keys dashboard.`
管理路由上的無效普通 API 金鑰	403	`Invalid management token`
存取令牌範圍過低	403	`Access token scope '<have>' is insufficient; '<need>' required.`

「無效管理令牌」表示 bearer 未被接受為管理憑證。它不會告訴您要鑄造哪個系列。請使用上表：推斷金鑰需要 manage 範圍；遠端 CLI 需要 oma_live_…；儀表板使用會話 Cookie。

建議的最小權限選擇

呼叫者	用途
瀏覽器	儀表板會話
伺服器主機上的 CLI	機器令牌
筆記型電腦上與遠端伺服器通訊的 CLI	來自 `omniroute connect` 的 `oma_live_…`
CI / 腳本 (僅限管理)	具有最小作用範圍的 `oma_live_…`
必須同時呼叫 `/v1` 和 `/api` 的 CI	具有 `manage` 的 API 金鑰或兩個憑證