Tunnel Group Backends - ngrok documentation

Create Tunnel Group Backend

Create a new TunnelGroup backend

Request

POST /backends/tunnel_group

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme tunnel group","labels":{"baz":"qux","foo":"bar"},"metadata":"{\"environment\": \"staging\"}"}' \
https://api.ngrok.com/backends/tunnel_group

Parameters

Name	Type	Description
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar

Response

Returns a 201 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:37Z",
  "description": "acme tunnel group",
  "id": "bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg",
  "labels": {
    "baz": "qux",
    "foo": "bar"
  },
  "metadata": "{\"environment\": \"staging\"}",
  "tunnels": [],
  "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this TunnelGroup backend
`uri`	string	URI of the TunnelGroupBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar
`tunnels`	Ref	tunnels matching this backend

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete Tunnel Group Backend

Delete a TunnelGroup backend by ID.

Request

DELETE /backends/tunnel_group/{id}

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg

Response

Returns a 204 response with no body on success

Get Tunnel Group Backend

Get detailed information about a TunnelGroup backend by ID

Request

GET /backends/tunnel_group/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg

Response

Returns a 200 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:37Z",
  "description": "acme tunnel group",
  "id": "bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg",
  "labels": {
    "baz": "qux",
    "foo": "bar"
  },
  "metadata": "{\"environment\": \"staging\"}",
  "tunnels": [],
  "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this TunnelGroup backend
`uri`	string	URI of the TunnelGroupBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar
`tunnels`	Ref	tunnels matching this backend

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

List Tunnel Group Backends

List all TunnelGroup backends on this account

Request

GET /backends/tunnel_group

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/tunnel_group

Response

Returns a 200 response on success

Example Response

{
  "backends": [
    {
      "created_at": "2025-09-04T10:11:37Z",
      "description": "acme tunnel group",
      "id": "bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg",
      "labels": {
        "baz": "qux",
        "foo": "bar"
      },
      "metadata": "{\"environment\": \"staging\"}",
      "tunnels": [],
      "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg"
    }
  ],
  "next_page_uri": null,
  "uri": "https://api.ngrok.com/backends/tunnel_group"
}

Fields

Name	Type	Description
`backends`	TunnelGroupBackend	the list of all TunnelGroup backends on this account
`uri`	string	URI of the TunnelGroup backends list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

TunnelGroupBackend fields

Name	Type	Description
`id`	string	unique identifier for this TunnelGroup backend
`uri`	string	URI of the TunnelGroupBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar
`tunnels`	Ref	tunnels matching this backend

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Update Tunnel Group Backend

Update TunnelGroup backend by ID

Request

PATCH /backends/tunnel_group/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg

Parameters

Name	Type	Description
`id`	string
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar

Response

Returns a 200 response on success

Example Response

{
  "created_at": "2025-09-04T10:11:37Z",
  "description": "acme tunnel group",
  "id": "bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg",
  "labels": {
    "baz": "qux",
    "foo": "bar"
  },
  "metadata": "{\"environment\": \"production\"}",
  "tunnels": [],
  "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_32ELHbnXi9wRIKSn0iP5hzlPTQg"
}

Fields

Name	Type	Description
`id`	string	unique identifier for this TunnelGroup backend
`uri`	string	URI of the TunnelGroupBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`labels`	Map<string, string>	labels to watch for tunnels on, e.g. app->foo, dc->bar
`tunnels`	Ref	tunnels matching this backend

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Universal Gateway

Traffic Policy

Secure Tunnels

Observability

IAM

SSH Certificates

Partners

​Create Tunnel Group Backend

​Request

​Example Request

​Parameters

​Response

​Example Response

​Fields

​Ref fields

​Delete Tunnel Group Backend

​Request

​Example Request

​Response

​Get Tunnel Group Backend

​Request

​Example Request

​Response

​Example Response

​Fields

​Ref fields

​List Tunnel Group Backends

​Request

​Example Request

​Response

​Example Response

​Fields

​TunnelGroupBackend fields

​Ref fields

​Update Tunnel Group Backend

​Request

​Example Request

​Parameters

​Response

​Example Response

​Fields

​Ref fields

Create Tunnel Group Backend

Request

Example Request

Parameters

Response

Example Response

Fields

Ref fields

Delete Tunnel Group Backend

Request

Example Request

Response

Get Tunnel Group Backend

Request

Example Request

Response

Example Response

Fields

Ref fields

List Tunnel Group Backends

Request

Example Request

Response

Example Response

Fields

TunnelGroupBackend fields

Ref fields

Update Tunnel Group Backend

Request

Example Request

Parameters

Response

Example Response

Fields

Ref fields