Manage Tunnels

CRUD plus a 24-hour soft-delete grace window for tunnel resources. See the Tunnels API overview for naming rules, lifecycle states, and TLS modes.

POST /tunnels

Create a new tunnel. The response includes a connect_secret shown once — store it securely.

• tls_mode: "edge" (default): the tunnel is active immediately and routable at {tunnel_name}.inkboxwire.com.
• tls_mode: "passthrough": the tunnel starts in awaiting_cert. You must then submit a CSR via /sign-csr to transition to active.

Rate-limited to 10 successful creates per organization per day.

Request body

Request example

JSON

Response (201)

JSON

Error responses

Code examples

cURL

cURL

JavaScript

Python

GET /tunnels

List all tunnels in the caller's organization (excludes deleted). Each entry includes a live currently_connected flag.

Response (200)

JSON

Code examples

cURL

cURL

JavaScript

Python

GET /tunnels/{tunnel_id}

Fetch a single tunnel by ID. Includes a live currently_connected flag.

Path parameters

Code examples

cURL

cURL

JavaScript

Python

PATCH /tunnels/{tunnel_id}

Update the tunnel's description. tunnel_name and tls_mode are immutable — create a new tunnel if you need a different name or mode.

Path parameters

Request body

Code examples

cURL

cURL

JavaScript

Python

DELETE /tunnels/{tunnel_id}

Move a tunnel into a 24-hour delete grace window. Inbound traffic stops immediately and status flips to delete_pending. The tunnel name stays reserved for your organization for 24 hours; after that, the tunnel is deleted and the name is released.

To undo within the grace window, call POST /tunnels/{id}/restore. Idempotent — calling delete on a delete_pending tunnel is a no-op.

Path parameters

Response (200)

Returns the updated Tunnel object. status is delete_pending and restore_deadline_at is set to 24 hours from now.

Code examples

cURL

cURL

JavaScript

Python

POST /tunnels/{tunnel_id}/restore

Undo a delete_pending deletion during the 24-hour grace window.

• edge tunnels return to active.
• passthrough tunnels return to active if a still-valid signed cert is on file; otherwise awaiting_cert.

Path parameters

Error responses

Code examples

cURL

cURL

JavaScript

Python

DELETE /tunnels/{tunnel_id}/force

Skip the 24-hour grace window and finalize a delete_pending tunnel immediately. The name is released for re-use right away.

Auth: API key or Clerk JWT only. The grace window exists to undo accidental deletes; force-finalize bypasses that net.

Path parameters

Error responses

Code examples

cURL

cURL

JavaScript

Python