이 페이지는 hs-sql-agent 2.0.2 소스에 실제로 존재하는 controller route를 나열하지만, controller 노출 여부는 선택한 capability에 따라 달라집니다. 번들 Admin UI는 일반적으로 내장 identity 구성을 사용하며, 기존 ASP.NET Core host에 임베드할 때는 다른 구성을 선택할 수 있습니다.
인증, 권한 부여, MVC ownership
Admin API capability를 선택하면 공개 mount는 /api로 고정됩니다. /auth/role, /runtime/db-management 같은 canonical permission path는 권한 부여 리소스 식별자이지 HTTP path가 아닙니다.
내장 identity 모드에서는 보호된 Admin route에 HsSqlAgent 인증과 canonical permission/action check가 적용됩니다. first-run, sign-in, 일부 OIDC / password-recovery endpoint, MFA challenge completion 등에는 필요한 익명 예외가 있습니다.
host-authorization 모드에서는 인증 기본값과 authorization policy를 호스트가 소유합니다. 요청된 canonical permission key는 HsSqlAgentPermissionResource.Permissions를 통해 호스트에 전달됩니다. modular host 모드의 UseHsSqlAgentAdminApi()는 의도적으로 MapControllers()를 호출하지 않으므로 MVC controller endpoint mapping도 호스트가 소유합니다.
자세한 내용은 권한을 참고하세요.
아래 Auth, Member, Role 절은 내장 identity capability를 선택한 구성에만 적용됩니다.
Auth — /api/Auth
| Method | Route | 용도 |
|---|---|---|
| GET | /api/Auth/first-run | 초기 설정 상태 확인 |
| POST | /api/Auth/sign-in | Admin credential 인증 |
| POST | /api/Auth/sign-up | 허용된 first-run flow에서 첫 Admin 생성 |
| POST | /api/Auth/refresh-token | refresh credential 교환 |
| POST | /api/Auth/sign-out | 현재 session 종료 |
| GET | /api/Auth/sessions | 현재 사용자의 session 목록 |
| DELETE | /api/Auth/sessions/{sessionId} | 특정 session 폐기 |
| DELETE | /api/Auth/sessions | 다른 session 폐기 |
| GET | /api/Auth/oidc/status | OIDC 사용 가능 상태 확인 |
| GET | /api/Auth/oidc/login | OIDC login 시작 |
| GET | /api/Auth/oidc/callback | external-login callback |
| POST | /api/Auth/oidc/exchange | short-lived OIDC login code 교환 |
| GET | /api/Auth/mfa/status | MFA 상태 확인 |
| POST | /api/Auth/mfa/setup | TOTP setup 시작 |
| POST | /api/Auth/mfa/confirm | TOTP setup 확인 |
| POST | /api/Auth/mfa/disable | 검증 후 TOTP 비활성화 |
| POST | /api/Auth/mfa/verify | MFA sign-in challenge 완료 |
| POST | /api/Auth/forgot-password | password reset 요청 |
| POST | /api/Auth/reset-password | reset token 사용 후 새 password 설정 |
| GET | /api/Auth/account | 현재 account profile 조회 |
| PUT | /api/Auth/account | username/email 수정 |
| PUT | /api/Auth/account/password | 현재 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 |
Self-lockout 및 lifecycle guardrail은 멤버와 역할을 참고하십시오.
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 | /runtime/db-management → view |
| GET | /api/DbManagement/{id} | /runtime/db-management → view |
| POST | /api/DbManagement | /runtime/db-management → create |
| PUT | /api/DbManagement/{id} | /runtime/db-management → edit |
| DELETE | /api/DbManagement/{id} | /runtime/db-management → delete |
| GET | /api/DbManagement/{id}/schemas | /runtime/db-management → view |
| GET | /api/DbManagement/{id}/tables?schema=... | /runtime/db-management → view |
| GET | /api/DbManagement/{id}/columns?schema=...&table=... | /runtime/db-management → view |
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-key runtime — /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 endpoint는 클라이언트 설정 생성에 사용하는 configured MCP public endpoint를 반환합니다.
Custom Tools — /api/CustomSqlTool
| Method | Route | 용도 |
|---|---|---|
| GET | /api/CustomSqlTool | 도구 목록 |
| GET | /api/CustomSqlTool/{id} | 단일 도구 조회 |
| POST | /api/CustomSqlTool | draft 생성 |
| PUT | /api/CustomSqlTool/{id} | draft 수정 |
| DELETE | /api/CustomSqlTool/{id} | 도구 삭제 |
| GET | /api/CustomSqlTool/{id}/revisions | revision 목록 |
| GET | /api/CustomSqlTool/{id}/impact | impact/dependency 확인 |
| POST | /api/CustomSqlTool/{id}/publish | validate 후 publish |
| POST | /api/CustomSqlTool/{id}/disable | published tool 비활성화 |
| POST | /api/CustomSqlTool/{id}/rollback/{revisionId} | validate 후 rollback |
| POST | /api/CustomSqlTool/test-execute | 테스트 실행. DML test path는 preview만 하고 commit하지 않음 |
이 route는 작업에 따라 /runtime/custom-tools의 view, create, edit, delete 권한을 사용합니다.
Audit 및 Operability — /api/runtime
| 영역 | Route |
|---|---|
| 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 |
Filter, response field, permission은 감사와 운영 상태를 참고하십시오.
Security Policy — /api/runtime/security
| Method | Route | 권한 |
|---|---|---|
| GET | /api/runtime/security | /runtime/security → view |
| PUT | /api/runtime/security | /runtime/security → edit |
Credential status
2.0.2에는 GET /api/Credential/status가 존재하며 간단한 Credential API running status를 반환합니다. 해당 controller 자체에는 [Authorize] attribute가 없습니다. 인증된 credential-management API가 아니라 범위가 매우 좁은 status endpoint로 취급하십시오.
오류 및 호환성
Controller는 validation 400, authentication/authorization 401/403, missing resource 404, conflicting tool/role state 409, oversized audit export 413, applicable bounded SQL-operation pressure 429 같은 일반 HTTP status code를 사용합니다.
외부 자동화에서 이 API를 사용한다면 2.0.2을 고정하고 실제 소비하는 response model을 검증하십시오. 이 페이지는 route와 중요한 계약을 기록하지만 모든 Admin view model을 영구적인 external SDK 계약으로 간주하지 않습니다.