本頁列出 hs-sql-agent 原始碼中實際存在的 controller routes，但 controller 是否公開取決於選用的 capability。內附 Admin UI 一般使用內建身分組合；嵌入既有 ASP.NET Core host 時則可以選擇不同組合。
身分驗證、授權與 MVC ownership
選用 Admin API capability 時，公開掛載固定為 /api。/auth/role、/runtime/db-management 等 canonical permission paths 是授權資源識別碼，不是 HTTP paths。
在內建身分模式下，受保護的 Admin routes 使用 HsSqlAgent 身分驗證與 canonical permission/action 檢查；first-run、sign-in、部分 OIDC / password-recovery endpoints、MFA challenge completion 等流程有必要的匿名例外。
在 host-authorization 模式下，身分驗證預設值與 authorization policy 都由宿主擁有；要求的 canonical permission keys 會透過 HsSqlAgentPermissionResource.Permissions 傳給宿主。modular host 模式中的 UseHsSqlAgentAdminApi() 刻意不呼叫 MapControllers()，MVC controller endpoint mapping 由宿主決定。
請見 權限。
下方 Auth、Member、Role 三節只適用於已選用內建身分 capability 的部署。
Auth — /api/Auth
| Method | Route | 用途 |
|---|---|---|
| GET | /api/Auth/first-run | 檢查首次設定狀態 |
| POST | /api/Auth/sign-in | 管理員登入 |
| POST | /api/Auth/sign-up | 在允許的首次設定流程建立第一位管理員 |
| POST | /api/Auth/refresh-token | 交換 refresh credential |
| POST | /api/Auth/sign-out | 結束目前工作階段 |
| GET | /api/Auth/sessions | 列出目前使用者的工作階段 |
| DELETE | /api/Auth/sessions/{sessionId} | 撤銷一個工作階段 |
| DELETE | /api/Auth/sessions | 撤銷其他工作階段 |
| GET | /api/Auth/oidc/status | 檢查 OIDC 是否可用 |
| GET | /api/Auth/oidc/login | 開始 OIDC 登入 |
| GET | /api/Auth/oidc/callback | 外部登入 callback |
| POST | /api/Auth/oidc/exchange | 交換短效 OIDC login code |
| GET | /api/Auth/mfa/status | 檢查 MFA 狀態 |
| POST | /api/Auth/mfa/setup | 開始設定 TOTP |
| POST | /api/Auth/mfa/confirm | 確認 TOTP 設定 |
| POST | /api/Auth/mfa/disable | 驗證後停用 TOTP |
| POST | /api/Auth/mfa/verify | 完成 MFA 登入 challenge |
| POST | /api/Auth/forgot-password | 要求重設密碼 |
| POST | /api/Auth/reset-password | 使用 reset token 重設密碼 |
| GET | /api/Auth/account | 讀取目前帳號 |
| PUT | /api/Auth/account | 更新使用者名稱 / email |
| PUT | /api/Auth/account/password | 修改密碼 |
Members — /api/Member
| Method | Route | 權限 |
|---|---|---|
| POST | /api/Member | /auth/user → create |
| GET | /api/Member | /auth/user → view |
| PUT | /api/Member/{id}/roles | /auth/user → edit |
| PUT | /api/Member/{id}/status | /auth/user → edit |
| DELETE | /api/Member/{id}/sessions | /auth/user → edit |
| PUT | /api/Member/{id}/password-change-required | /auth/user → edit |
| DELETE | /api/Member/{id} | /auth/user → delete |
避免管理員把自己鎖在系統外的保護規則，請見 成員與角色。
Roles — /api/Role
| Method | Route | 權限 |
|---|---|---|
| GET | /api/Role | /auth/role → view |
| POST | /api/Role | /auth/role → create |
| PUT | /api/Role/{id} | /auth/role → edit |
| DELETE | /api/Role/{id}?force=false | /auth/role → delete |
| GET | /api/Role/{id}/dependencies | /auth/role → view |
| GET | /api/Role/permission-action-templates | /auth/role → view |
Database Management — /api/DbManagement
| Method | Route | 權限 |
|---|---|---|
| GET | /api/DbManagement | DB management view |
| GET | /api/DbManagement/{id} | DB management view |
| POST | /api/DbManagement | DB management create |
| PUT | /api/DbManagement/{id} | DB management edit |
| DELETE | /api/DbManagement/{id} | DB management delete |
| GET | /api/DbManagement/{id}/schemas | DB management view |
| GET | /api/DbManagement/{id}/tables?schema=... | DB management view |
| GET | /api/DbManagement/{id}/columns?schema=...&table=... | DB management view |
此處的 DB management 代表 /runtime/db-management。
Semantic metadata — /api/DbSemantic
| Method | Route | 權限 |
|---|---|---|
| GET | /api/DbSemantic/{dbManagementId} | semantic view |
| GET | /api/DbSemantic/{dbManagementId}/model | semantic view |
| POST | /api/DbSemantic | semantic edit |
| DELETE | /api/DbSemantic/{id} | semantic edit |
| POST | /api/DbSemantic/relationship | semantic edit |
| DELETE | /api/DbSemantic/relationship/{id} | semantic edit |
| POST | /api/DbSemantic/metric | semantic edit |
| DELETE | /api/DbSemantic/metric/{id} | semantic edit |
semantic 代表 /runtime/db-management/semantic。
MCP 金鑰執行階段 — /api/runtime
| Method | Route | 權限 |
|---|---|---|
| GET | /api/runtime/mcp-keys | MCP keys view |
| GET | /api/runtime/mcp-keys/available-tools?dbManagementId=... | MCP keys view |
| POST | /api/runtime/mcp-keys | MCP keys create |
| PUT | /api/runtime/mcp-keys/{id} | MCP keys edit |
| POST | /api/runtime/mcp-keys/{id}/rotate | MCP keys edit |
| POST | /api/runtime/mcp-keys/{id}/clone | MCP keys create |
| POST | /api/runtime/mcp-keys/{id}/revoke | MCP keys revoke |
| POST | /api/runtime/mcp-keys/test-db-connection | 已設定的 MCP-key / DB create-edit 權限之一 |
| GET | /api/runtime/client-config | MCP keys view |
client-config 路由會回傳產生 MCP 用戶端設定時使用的公開端點。
Custom Tools — /api/CustomSqlTool
| Method | Route | 用途 |
|---|---|---|
| GET | /api/CustomSqlTool | 列出工具 |
| GET | /api/CustomSqlTool/{id} | 讀取單一工具 |
| POST | /api/CustomSqlTool | 建立草稿 |
| PUT | /api/CustomSqlTool/{id} | 編輯草稿 |
| DELETE | /api/CustomSqlTool/{id} | 刪除 |
| GET | /api/CustomSqlTool/{id}/revisions | 取得修訂版本 |
| GET | /api/CustomSqlTool/{id}/impact | 查看影響與相依關係 |
| POST | /api/CustomSqlTool/{id}/publish | 驗證後發布 |
| POST | /api/CustomSqlTool/{id}/disable | 停用 |
| POST | /api/CustomSqlTool/{id}/rollback/{revisionId} | 驗證後回復到指定修訂版本 |
| POST | /api/CustomSqlTool/test-execute | 測試；DML 只預覽、不提交 |
這些路由會依操作檢查 /runtime/custom-tools 的 view、create、edit、delete 權限。
Audit / Operability — /api/runtime
| 區域 | 路由 |
|---|---|
| Audit | /audit, /audit/daily-summary, /audit/export, /audit/retention, /audit/retention/dry-run, /audit/retention/execute |
| Operability | /operability/metrics, /operability/db-health, /operability/key-usage, /operability/deliveries, /operability/deliveries/{id}/retry |
Security Policy — /api/runtime/security
| Method | Route | 權限 |
|---|---|---|
| GET | /api/runtime/security | /runtime/security → view |
| PUT | /api/runtime/security | /runtime/security → edit |
Credential status
hs-sql-agent 提供 GET /api/Credential/status，只回傳簡單的 Credential API 運作狀態；controller 本身沒有 [Authorize] attribute。應把它視為用途有限的狀態端點，而不是經驗證的憑證管理 API。
錯誤與相容性
Controllers 使用一般 HTTP status code，例如驗證錯誤 400、身分驗證 / 授權錯誤 401 / 403、找不到資源 404、衝突 409、稽核匯出過大 413，以及部分受限制 SQL 壓力路徑的 429。
若外部自動化直接依賴這套 API，請固定使用 hs-sql-agent，並驗證實際使用的 response model。本文件刻意記錄路由與重要契約，不把所有管理端 view model 宣稱成永久、版本化的外部 SDK。