Jump to

Manage Tunnels

A read-mostly surface on tunnel resources: list, get, and update metadata. Tunnels are provisioned and destroyed via the identity surface — see Create identity and Delete identity. See the Tunnels API overview for naming rules, lifecycle states, and TLS modes.

List tunnels GET

GET /tunnels

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

Response (200)

JSON

Code examples

Get tunnel GET

GET /tunnels/{tunnel_id}

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

Path parameters

Parameter	Type	Description
`tunnel_id`	UUID	Tunnel ID

Code examples

Update tunnel PATCH

PATCH /tunnels/{tunnel_id}

Update the tunnel's metadata. tunnel_name and tls_mode are immutable — renames flow from identity-handle renames, and TLS mode is fixed at creation.

Path parameters

Parameter	Type	Description
`tunnel_id`	UUID	Tunnel ID

Request body

Field	Type	Required	Description
`metadata`	object \| null	No	Free-form JSON object for your own use, capped at 4 KB serialized. Pass `{}` or `null` to clear; omit to leave unchanged. Returned as-is on read.

Code examples

Tunnel object

Field	Type	Description
`id`	UUID	Unique tunnel identifier
`organization_id`	string	Owning organization
`tunnel_name`	string	Subdomain label. Tracks the owning identity's handle; renames flow from identity-handle renames. Hostname is e.g. `my-agent.inkboxwire.com`.
`public_host`	string	Fully qualified public hostname for this tunnel (e.g. `my-agent.inkboxwire.com`). The third-party-facing endpoint.
`zone`	string	Tunnel zone host (`inkboxwire.com`). Your agent connects to `https://{zone}/_system/connect`.
`tls_mode`	string	`"edge"` or `"passthrough"`. Immutable.
`cert_pem`	string \| null	Signed cert PEM (passthrough only, after first `/sign-csr`)
`cert_fingerprint_sha256`	string \| null	SHA-256 fingerprint of `cert_pem`, useful for monitoring rotations
`cert_expires_at`	string \| null	ISO 8601 expiry of `cert_pem`. Renew before this date.
`status`	string	`awaiting_cert` or `active`
`last_connected_at`	string \| null	ISO 8601 timestamp of the most recent agent connection
`last_connected_ip_addr`	string \| null	Client IP recorded at the most recent agent connection
`currently_connected`	boolean	`true` if at least one agent connection is currently registered
`metadata`	object	Free-form JSON object set via PATCH; capped at 4 KB serialized. Returned as-is. Defaults to `{}`.
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601