This page lists controller routes that exist in the hs-sql-agent source, but controller availability is capability-dependent. The bundled Admin UI normally uses the built-in identity composition; an embedding host can select a different composition.
Authentication, authorization, and MVC ownership
When the Admin API capability is selected, its public mount remains /api. Canonical permission paths such as /auth/role and /runtime/db-management are authorization resource identifiers, not HTTP paths.
In built-in identity mode, protected Admin routes use HsSqlAgent authentication plus canonical permission/action checks, with anonymous exceptions for flows such as first-run, sign-in, selected OIDC/password-recovery endpoints, and MFA challenge completion.
In host-authorization mode, the host owns authentication defaults and its authorization policy. Requested canonical permission keys arrive through HsSqlAgentPermissionResource.Permissions. In modular host mode UseHsSqlAgentAdminApi() deliberately does not call MapControllers(); the host owns controller endpoint mapping for the MVC application.
See Permissions.
The Auth, Member, and Role sections below apply only when the built-in identity capability is selected.
Auth — /api/Auth
| Method | Route | Purpose |
|---|---|---|
| GET | /api/Auth/first-run | inspect initial-setup state |
| POST | /api/Auth/sign-in | authenticate Admin credentials |
| POST | /api/Auth/sign-up | create the first Admin during allowed first-run flow |
| POST | /api/Auth/refresh-token | exchange a refresh credential |
| POST | /api/Auth/sign-out | end the current session |
| GET | /api/Auth/sessions | list current user’s sessions |
| DELETE | /api/Auth/sessions/{sessionId} | revoke one session |
| DELETE | /api/Auth/sessions | revoke other sessions |
| GET | /api/Auth/oidc/status | inspect OIDC availability |
| GET | /api/Auth/oidc/login | start OIDC login |
| GET | /api/Auth/oidc/callback | external-login callback |
| POST | /api/Auth/oidc/exchange | exchange the short-lived OIDC login code |
| GET | /api/Auth/mfa/status | inspect MFA state |
| POST | /api/Auth/mfa/setup | begin TOTP setup |
| POST | /api/Auth/mfa/confirm | confirm TOTP setup |
| POST | /api/Auth/mfa/disable | disable TOTP after validation |
| POST | /api/Auth/mfa/verify | complete an MFA sign-in challenge |
| POST | /api/Auth/forgot-password | request password reset |
| POST | /api/Auth/reset-password | consume reset token and set new password |
| GET | /api/Auth/account | read current account profile |
| PUT | /api/Auth/account | update username/email |
| PUT | /api/Auth/account/password | change current password |
Members — /api/Member
| Method | Route | Permission |
|---|---|---|
| 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 |
See Members & Roles for self-lockout and lifecycle guardrails.
Roles — /api/Role
| Method | Route | Permission |
|---|---|---|
| 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 | Permission |
|---|---|---|
| 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 | Permission |
|---|---|---|
| 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 |
Here semantic means /runtime/db-management/semantic.
MCP-key runtime — /api/runtime
| Method | Route | Permission |
|---|---|---|
| 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 | one of the configured MCP-key/DB create-edit permissions |
| GET | /api/runtime/client-config | MCP keys view |
The client-config endpoint returns the configured MCP public endpoint used to generate client setup.
Custom Tools — /api/CustomSqlTool
| Method | Route | Purpose |
|---|---|---|
| GET | /api/CustomSqlTool | list tools |
| GET | /api/CustomSqlTool/{id} | get one tool |
| POST | /api/CustomSqlTool | create draft |
| PUT | /api/CustomSqlTool/{id} | edit draft |
| DELETE | /api/CustomSqlTool/{id} | delete tool |
| GET | /api/CustomSqlTool/{id}/revisions | list revisions |
| GET | /api/CustomSqlTool/{id}/impact | inspect impact/dependencies |
| POST | /api/CustomSqlTool/{id}/publish | validate and publish |
| POST | /api/CustomSqlTool/{id}/disable | disable published tool |
| POST | /api/CustomSqlTool/{id}/rollback/{revisionId} | validate and roll back |
| POST | /api/CustomSqlTool/test-execute | test execution; DML test path previews and does not commit |
These routes use /runtime/custom-tools with view, create, edit, or delete as appropriate.
Audit and operability — /api/runtime
| Area | Routes |
|---|---|
| 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 |
See Audit and Operability for filters, response fields, and permissions.
Security Policy — /api/runtime/security
| Method | Route | Permission |
|---|---|---|
| GET | /api/runtime/security | /runtime/security → view |
| PUT | /api/runtime/security | /runtime/security → edit |
Credential status
GET /api/Credential/status is available and returns a simple Credential API running status. The controller itself has no [Authorize] attribute. Treat it as a narrow status endpoint, not as an authenticated credential-management API.
Errors and compatibility
Controllers use ordinary HTTP status codes such as 400 for validation, 401/403 for authentication/authorization, 404 for missing resources, 409 for conflicting tool/role state, 413 for oversized audit export, and 429 for bounded SQL-operation pressure where applicable.
For client automation, pin the release you deploy and validate the actual response model you consume. This page intentionally documents routes and important contracts without pretending that every Admin view model is a permanently versioned external SDK.