Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Tunnels API
description: Stable public URLs for your AI agents — receive HTTP, WebSocket, and raw-TCP traffic over a single persistent connection

---


# Tunnels API

A tunnel gives your agent a stable public URL — `{tunnel_name}.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.

API base URL:


## Quick start

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

[Get API key](https://inkbox.ai/console/api-keys)


## Tunnel naming rules

Pick a name when you create the tunnel — it becomes the subdomain at `{tunnel_name}.inkboxwire.com`.

- 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. Names are unique across all Inkbox customers within an environment.

## Lifecycle states

A tunnel always has one of four `status` values:

| Status | Meaning |
| :--- | :--- |
| `awaiting_cert` | Passthrough mode only. The tunnel is provisioned but you haven't signed a CSR yet. |
| `active` | Routable end-to-end. Inbound traffic flows to your agent. |
| `delete_pending` | You called `DELETE`. Inbound traffic stops immediately. The name stays reserved for 24 hours so you can `restore` if it was a mistake. |
| `deleted` | Terminal. The name is released and may be claimed by anyone. |

## TLS modes

Choose at creation time; immutable afterwards.

| Mode | Who terminates TLS | Setup | When to use |
| :--- | :--- | :--- | :--- |
| `edge` (default) | Inkbox at our edge, with a managed cert | Zero — `active` immediately | Most users. Webhooks, real-time APIs, simple integrations. |
| `passthrough` | You, in your own agent | Sign a CSR via `/sign-csr`; we issue a 90-day cert | Compliance constraints requiring TLS to terminate inside your network, or client-side cert pinning. |

See [Passthrough TLS](/docs/api/tunnels/passthrough) for the full passthrough flow.

## Connecting your agent

When you create a tunnel, the response includes a one-time `connect_secret`. Your agent uses this secret to open a persistent connection to your tunnel hostname; once connected, inbound traffic from third parties is routed to your agent in real time.

The `connect_secret` is shown **once** at creation — store it securely. If you lose it, rotate it via [Connect secret](/docs/api/tunnels/secret).

> **SDK helpers for the agent-side connection are coming soon.** For early access to the connection protocol, [contact us](mailto:hello@inkbox.ai).

## Manage tunnels


  **[Create tunnel](/docs/api/tunnels/manage)** `POST` `/api/v1/tunnels` — Provision a new tunnel and receive its connect secret

  **[List tunnels](/docs/api/tunnels/manage)** `GET` `/api/v1/tunnels` — List all tunnels in your organization

  **[Get tunnel](/docs/api/tunnels/manage)** `GET` `/api/v1/tunnels/{tunnel_id}` — Get a single tunnel by ID, including live connection status

  **[Update tunnel](/docs/api/tunnels/manage)** `PATCH` `/api/v1/tunnels/{tunnel_id}` — Update description or metadata (name and TLS mode are immutable)

  **[Delete tunnel](/docs/api/tunnels/manage)** `DELETE` `/api/v1/tunnels/{tunnel_id}` — Take a tunnel offline; restorable for 24 hours

  **[Restore tunnel](/docs/api/tunnels/manage)** `POST` `/api/v1/tunnels/{tunnel_id}/restore` — Undo a delete during the 24-hour grace window

  **[Force-delete tunnel](/docs/api/tunnels/manage)** `DELETE` `/api/v1/tunnels/{tunnel_id}/force` — Skip the grace window and finalize a pending delete (admin only)


## Connect secret


  **[Rotate connect secret](/docs/api/tunnels/secret)** `POST` `/api/v1/tunnels/{tunnel_id}/rotate-secret` — Generate a new connect secret for this tunnel


## Passthrough TLS


  **[Sign CSR](/docs/api/tunnels/passthrough)** `POST` `/api/v1/tunnels/{tunnel_id}/sign-csr` — Submit a CSR for a passthrough tunnel and receive a signed cert


## Additional resources

- [Identities API](/docs/api/identities)
- [Mail API](/docs/api/mail)
- [Phone API](/docs/api/phone)