> ## Documentation Index > Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a Tunnel > 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. ## OpenAPI ````yaml /openapi/source/external/netapps/netapps.json post /tunnels openapi: 3.1.0 info: version: 2.0.0 title: Telnyx API x-latency-category: responsive x-endpoint-cost: light description: SIP trunking, SMS, MMS, Call Control and Telephony Data Services. license: name: MIT identifier: MIT contact: email: support@telnyx.com servers: - url: https://api.telnyx.com/v2 description: Version 2.0.0 of the Telnyx API security: - bearerAuth: [] tags: - name: Networks description: Network operations - name: Public Internet Gateways description: Public Internet Gateway operations - name: WireGuard Interfaces description: WireGuard Interface operations - name: Tunnels description: >- Tunnels connect a Network to hosts behind a tunnel process within the user's network. - name: Network Routes description: Routes on a Network that send a CIDR to a next hop, such as a tunnel. - name: Tailscale Subnet Routers description: Tailscale Subnet Router operations - name: Virtual Cross Connects description: Virtual Cross Connect operations - name: Regions description: Regions - name: Global IPs description: Global IPs paths: /tunnels: post: tags: - Tunnels summary: Create a Tunnel description: >- 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. operationId: CreateTunnel requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TunnelCreate' example: name: chicago-dc responses: '201': description: Created. The response carries the tunnel token, once. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TunnelWithToken' example: data: id: 62d438d2-8a51-4c5e-9d0c-1f6b2a7e4c39 record_type: tunnel name: chicago-dc tunnel_token: tnl_example-token-shown-once status: inactive connection_count: 0 connections: [] created_at: '2026-10-21T15:04:05.123456Z' '422': description: >- Unprocessable entity: the body failed validation. `source.pointer` names the field. content: application/json: schema: $ref: '#/components/schemas/Errors' example: errors: - code: '10022' title: Unprocessable Entity detail: name is required source: pointer: /name default: $ref: '#/components/responses/GenericErrorResponse' components: schemas: TunnelCreate: type: object title: TunnelCreate required: - name properties: name: type: string minLength: 1 description: A user specified name for the tunnel. example: chicago-dc TunnelWithToken: title: TunnelWithToken allOf: - $ref: '#/components/schemas/Tunnel' - type: object properties: tunnel_token: type: string readOnly: true description: >- 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. example: tnl_example-token-shown-once Errors: properties: errors: type: array items: $ref: '#/components/schemas/Error' type: object Tunnel: type: object title: Tunnel properties: id: type: string format: uuid readOnly: true description: Identifies the resource. example: 62d438d2-8a51-4c5e-9d0c-1f6b2a7e4c39 record_type: type: string readOnly: true description: Identifies the type of the resource. example: tunnel name: type: string minLength: 1 description: A user specified name for the tunnel. example: chicago-dc status: type: string enum: - inactive - healthy - degraded readOnly: true description: >- `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. example: healthy connection_count: type: integer minimum: 0 readOnly: true description: The number of tunnel processes connected with the tunnel's token. example: 2 connections: type: array readOnly: true description: The tunnel processes connected with the tunnel's token. items: $ref: '#/components/schemas/TunnelConnection' created_at: type: string format: date-time readOnly: true description: >- ISO 8601 formatted date-time indicating when the resource was created. example: '2026-10-21T15:04:05.123456Z' Error: required: - code - title properties: code: type: string title: type: string detail: type: string source: type: object properties: pointer: description: JSON pointer (RFC6901) to the offending entity. type: string parameter: description: Indicates which query parameter caused the error. type: string meta: type: object additionalProperties: true type: object TunnelConnection: type: object title: TunnelConnection description: A tunnel process connected to the tunnel. properties: hostname: type: string description: >- The name the host reports for itself. Preview: empty until the CLI reports it. example: dc1-tunnel-a version: type: string description: >- The `telnyx-edge` CLI version of the process. Preview: empty until the CLI reports it. example: 0.6.0 region_code: type: string description: >- The Telnyx region the process is connected to. Preview: empty until the CLI reports it. example: chicago-il connected_at: type: string format: date-time description: When the process connected. example: '2026-10-21T15:04:05.123456Z' responses: GenericErrorResponse: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Errors' securitySchemes: bearerAuth: type: http scheme: bearer ````