---
title: "Create a Tunnel"
method: POST
path: "/tunnels"
tags: ["Tunnels"]
---

# Create a Tunnel

`POST /tunnels`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/tunnels`
- Auth: HTTP bearer

Creates a tunnel and returns its `tunnel_token`. The token is the only credential the tunnel process needs, and this response and `POST /tunnels/{id}/actions/rotate_token` are the only ones that return it. A new tunnel is `inactive` until a tunnel process connects with the token.

## Request body

- TunnelCreate
  - `name` string, required: A user specified name for the tunnel.

## Response `201`

Created. The response carries the tunnel token, once.

- object
  - `data` TunnelWithToken
    - `id` string, uuid: Identifies the resource.
    - `record_type` string: Identifies the type of the resource.
    - `name` string: A user specified name for the tunnel.
    - `status` 'inactive' | 'healthy' | 'degraded': `inactive` when no tunnel process is connected, and `healthy` when one or more are. `degraded` (Preview, not reported yet) when a process is connected but fails to reach its destinations.
    - `connection_count` integer: The number of tunnel processes connected with the tunnel's token.
    - `connections` TunnelConnection[]: The tunnel processes connected with the tunnel's token.
      - `hostname` string: The name the host reports for itself. Preview: empty until the CLI reports it.
      - `version` string: The `telnyx-edge` CLI version of the process. Preview: empty until the CLI reports it.
      - `region_code` string: The Telnyx region the process is connected to. Preview: empty until the CLI reports it.
      - `connected_at` string, date-time: When the process connected.
    - `created_at` string, date-time: ISO 8601 formatted date-time indicating when the resource was created.
    - `tunnel_token` string: The credential that a tunnel process presents with `telnyx-edge tunnel run --token`. Returned only by create and rotate_token. Telnyx stores only a hash of it.

## Other responses

- `422`: Unprocessable entity: the body failed validation. `source.pointer` names the field.
- `default`: Unexpected error

## Changes

- **2026-10-26** `0f17b8167873`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api/changes/tunnels/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api/revisions/0f17b8167873?raw)