DB Proxy Routes

DB proxy routes are wire-protocol tunnels that let agents connect to a migrated database through KnoxCall using a localhost:<port> listener. They can be created for any migration the reviewer owns — the committed_secret_id must reference an existing tenant secret, but no particular migration status is required. Routes are removed only via DELETE /admin/migrations/:id/db-proxy-routes/:routeId; cancelling the migration does not delete them. The write endpoints (POST and DELETE) require migration_reviewer permission + 5-minute step-up. The GET (list) endpoint requires only tenant access to the migration — no migration_reviewer role or step-up.

POST /admin/migrations/:id/db-proxy-routes

Create a new wire-protocol proxy route for a migration. Auth: migration_reviewer + 5-minute step-up

Request body

Field	Required	Description
`protocol`	✅	Wire protocol: `postgres`, `mysql`, `mongodb`, `redis`, `sqlserver`
`upstream_host`	✅	Hostname or IP of the real database
`upstream_port`	✅	Port of the real database
`committed_secret_id`	✅	ID of the committed KnoxCall secret holding the database credentials
`credential_username`	✅	Database username to authenticate with. Required for every protocol except `redis`
`local_port`	conditional	Agent-local port the tunnel listens on (must be unique per agent). Required when `bind_mode` is `tcp`; must be 1024–65535 (privileged ports under 1024 are not supported)
`bind_mode`	—	How the agent listener is exposed: `tcp` (default), `unix`, or `pipe`
`unix_socket_path`	conditional	Absolute path (must start with `/`) for the listener. Required when `bind_mode` is `unix`
`pipe_name`	conditional	Simple named-pipe name (no backslashes) for the listener. Required when `bind_mode` is `pipe`
`upstream_database`	—	Database name to connect to
`upstream_username`	—	Stored upstream username for display/reference
`tls_mode`	—	`prefer` (default), `require`, `disable`
`agent_id`	—	Scope the tunnel to a specific agent UUID; omit for any agent
`allowed_uids`	—	Array of Unix UIDs allowed to use the tunnel
`secret_migration_item_id`	—	Associate the route with a specific migration item

Returns 409 if local_port is already in use for the same agent.

Response

{ "id": "route-uuid" }

Status 201 Created.

GET /admin/migrations/:id/db-proxy-routes

List all proxy routes for a migration. Auth: tenant access to the migration (no migration_reviewer role or step-up required)

Response

{
  "routes": [
    {
      "id": "route-uuid",
      "protocol": "postgres",
      "upstream_host": "prod-db.internal",
      "upstream_port": 5432,
      "upstream_database": "myapp",
      "upstream_username": "readonly",
      "tls_mode": "prefer",
      "local_port": 15432,
      "agent_id": null,
      "allowed_uids": [],
      "committed_secret_id": "secret-uuid",
      "secret_migration_item_id": "item-uuid",
      "enabled": true,
      "created_at": "2026-05-25T10:00:00Z",
      "updated_at": "2026-05-25T10:00:00Z"
    }
  ]
}

DELETE /admin/migrations/:id/db-proxy-routes/:routeId

Remove a proxy route. The agent tunnel is torn down immediately. Auth: migration_reviewer + 5-minute step-up

Response

{ "id": "route-uuid", "deleted": true }

Returns 404 if the route is not found for this migration and tenant.

Verification Events

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

DB Proxy Routes

DB Proxy Routes

POST /admin/migrations/:id/db-proxy-routes

Request body

Response

GET /admin/migrations/:id/db-proxy-routes

Response

DELETE /admin/migrations/:id/db-proxy-routes/:routeId

Response

​DB Proxy Routes

​POST /admin/migrations/:id/db-proxy-routes

​Request body

​Response

​GET /admin/migrations/:id/db-proxy-routes

​Response

​DELETE /admin/migrations/:id/db-proxy-routes/:routeId

​Response

DB Proxy Routes

POST /admin/migrations/:id/db-proxy-routes

Request body

Response

GET /admin/migrations/:id/db-proxy-routes

Response

DELETE /admin/migrations/:id/db-proxy-routes/:routeId

Response