使用 System-to-System API Key 呼叫管理 API

要讓 SaaS 後端、排程或其他系統自動化管理作業，先在 Admin UI 建立 System-to-System API Key，設定可操作的權限，再由外部後端透過 X-API-Key 呼叫現有 /api。不用寫程式去簽發 Key，也不必模擬管理員登入。

1. 在 Admin UI 簽發 Key

使用具有安全設定編輯權限的管理員帳號登入 Admin UI。
開啟 Runtime → Management API Keys。
輸入名稱，例如 production-integration，並設定到期時間。
勾選外部服務需要的管理權限。若要執行下方範例，請選 /runtime/db-management.view 與 /runtime/custom-tools.view。
點選 Issue key，立即複製產生的 Key；明文只會顯示一次。

請將 Key 存放在外部後端的 Secret Manager 或環境變數，不要放進前端程式碼、瀏覽器或版本庫。

2. 使用 Key 呼叫現有 API

例如，列出已設定的資料庫連線：

curl -X GET "https://agent.example.com/api/DbManagement" \
  -H "X-API-Key: ${HS_MANAGEMENT_API_KEY}"

或列出已建立的 Custom Tools：

curl -X GET "https://agent.example.com/api/CustomSqlTool" \
  -H "X-API-Key: ${HS_MANAGEMENT_API_KEY}"

3. 查看 API 回應

資料庫清單 API 成功時回傳 HTTP 200 與 JSON 陣列。以下只展示其中一筆的部分欄位：

[
  {
    "id": 1,
    "name": "Production DB",
    "sqlProvider": "PostgreSql",
    "host": "db.internal",
    "database": "orders",
    "isBootstrapManaged": false
  }
]

Key 可以呼叫哪些 API？

由 Admin UI 勾選的權限決定。只要有對應權限，同一把 Key 就能呼叫多個現有管理 API，不需要為每個端點重新建立 Key。

API	Permission
`GET /api/DbManagement`	`/runtime/db-management.view`
`GET /api/CustomSqlTool`	`/runtime/custom-tools.view`
`POST /api/CustomSqlTool`	`/runtime/custom-tools.create`
`POST /api/CustomSqlTool/{id}/publish`	`/runtime/custom-tools.edit`
`POST /api/DbManagement`	`/runtime/db-management.create`

如何查 Request／Response 規格？

請看實際 Request／Response 串接範例，其中有建立 Custom Tool 的 POST JSON 範例；其他 API 請參考管理 REST API 路由索引。尚未補齊的 Response Schema 持續追蹤於 Issue #295。

後續輪替或撤銷

需要輪替或撤銷時，回到 Runtime → Management API Keys 操作即可。外部服務只負責使用已簽發的 Key，不需要管理 Key 的簽發流程。