> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DB Proxy Routes

> Create, list, and delete wire-protocol proxy tunnels for migrated database credentials.

## 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

```json theme={"dark"}
{ "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

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{ "id": "route-uuid", "deleted": true }
```

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