Tunnels API

A tunnel gives your agent a stable public URL — my-agent.inkboxwire.com — that routes inbound HTTP, WebSocket, and raw-TCP traffic from third parties to your agent over a single persistent connection. No public IP, firewall hole, or reverse proxy needed on your end.

Every agent identity owns exactly one tunnel; the tunnel name always matches the identity's handle. Tunnels are provisioned automatically when you create an identity and torn down when you delete it. The Tunnels API is read-mostly — list, get, update metadata, and (for passthrough) sign a CSR.

API base URL:

https://inkbox.ai/api/v1/tunnels

Create an account and get your API key from the Inkbox console:

X-API-Key: YOUR_API_KEY

The tunnel name is always the identity's agent_handle. Handles, and therefore tunnel names, are globally unique across all Inkbox customers.

• 3–63 characters
• lowercase letters, digits, and hyphens only
• must start and end with a letter or digit
• no consecutive hyphens

Some names are reserved; you'll get a 409 if you pick one. See Manage identities for handle creation.

A tunnel always has one of two status values:

SDK enum mapping: the Python and TypeScript SDKs surface tunnel status through a TunnelStatus enum whose values are AWAITING_CERT and ACTIVE. The wire shape returned by the REST API uses the snake-case forms above.

Choose at creation time (via the nested tunnel.tls_mode on identity-create); immutable afterwards.

See Passthrough TLS for the full passthrough flow.

The tunnel object distinguishes two related host names:

• public_host — per-tunnel public hostname (e.g. my-agent.inkboxwire.com). Use this for the public URL third parties hit.
• zone — tunnel zone host (e.g. inkboxwire.com). The agent connects to https://{zone}/_system/connect here, not to https://{public_host}/_system/connect.

currently_connected reflects whether at least one agent connection is registered; last_connected_ip_addr captures the caller IP at the most recent /_system/hello. metadata is a customer-supplied free-form JSON object capped at 4 KB serialized.

The agent authenticates inbound connections on POST /_system/hello with two headers:

• x-tunnel-id: <tunnel UUID> — which tunnel the agent is dialing.
• x-api-key: <full API key> — the same REST API key the rest of the SDK uses.

Authorization rules:

• An identity-scoped API key may connect a tunnel iff the tunnel's owning identity matches the key's scoped identity.
• An admin-scoped API key may connect any tunnel in its org.

There is no per-tunnel secret. To rotate, rotate the customer's API key.

The Python and TypeScript SDKs ship a connect() helper that handles the persistent agent connection and graceful shutdown for you:

Python

Python

TypeScript

See the Tunnels capability guide for in-process handlers, WebSockets, and the full lifecycle.

/api/v1/tunnels

/api/v1/tunnels/{tunnel_id}

/api/v1/tunnels/{tunnel_id}

/api/v1/tunnels/{tunnel_id}/sign-csr

• Identities API
• Mail API
• Phone API