Edges TLS

Create TLS Edge

Create a TLS Edge

Request

POST /edges/tls

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme tls edge","metadata":"{\"environment\": \"staging\"}","hostports":["example.com:443"]}' \
https://api.ngrok.com/edges/tls

Parameters


`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate
`mutual_tls`	EndpointMutualTLSMutate
`tls_termination`	EndpointTLSTermination

EndpointBackendMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

EndpointIPPolicyMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policy_ids`	List<string>	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLSMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authority_ids`	List<string>	list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection

EndpointTLSTermination parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Response

Returns a 201 response on success

Example Response

{
    "id": "edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "description": "acme tls edge",
    "metadata": "{\"environment\": \"staging\"}",
    "created_at": "2023-07-31T23:17:45Z",
    "uri": "https://api.ngrok.com/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "hostports": ["example.com:443"],
    "backend": null,
    "ip_restriction": null,
    "mutual_tls": null,
    "tls_termination": null
}

Fields


`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields


`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Get TLS Edge

Get a TLS Edge by ID

Request

GET /edges/tls/{id}

Example Request

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

Response

Returns a 200 response on success

Example Response

{
    "id": "edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "description": "acme tls edge",
    "metadata": "{\"environment\": \"staging\"}",
    "created_at": "2023-07-31T23:17:45Z",
    "uri": "https://api.ngrok.com/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "hostports": ["example.com:443"],
    "backend": null,
    "ip_restriction": null,
    "mutual_tls": null,
    "tls_termination": null
}

Fields


`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields


`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

List TLS Edges

Returns a list of all TLS Edges on this account

Request

GET /edges/tls

Example Request

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

Response

Returns a 200 response on success

Example Response

{
    "tls_edges": [
        {
            "id": "edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
            "description": "acme tls edge",
            "metadata": "{\"environment\": \"staging\"}",
            "created_at": "2023-07-31T23:17:45Z",
            "uri": "https://api.ngrok.com/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
            "hostports": ["example.com:443"],
            "backend": null,
            "ip_restriction": null,
            "mutual_tls": null,
            "tls_termination": null
        },
        {
            "id": "edgtls_2TMGIEAvsu9Eg9xQVO6zgxZUAzM",
            "description": "acme tls edge",
            "created_at": "2023-07-31T23:17:33Z",
            "uri": "https://api.ngrok.com/edges/tls/edgtls_2TMGIEAvsu9Eg9xQVO6zgxZUAzM",
            "hostports": ["endpoint-example.com:443"],
            "backend": {
                "enabled": true,
                "backend": {
                    "id": "bkdhr_2TMGI9f8rFdzz5PANNNn2CTfES0",
                    "uri": "https://api.ngrok.com/backends/http_response/bkdhr_2TMGI9f8rFdzz5PANNNn2CTfES0"
                }
            },
            "ip_restriction": null,
            "mutual_tls": null,
            "tls_termination": null
        }
    ],
    "uri": "https://api.ngrok.com/edges/tls",
    "next_page_uri": null
}

Fields


`tls_edges`	TLSEdge	the list of all TLS Edges on this account
`uri`	string	URI of the TLS Edge list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

TLSEdge fields


`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields


`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Update TLS Edge

Updates a TLS Edge by ID. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.

Request

PATCH /edges/tls/{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/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1

Parameters


`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate
`mutual_tls`	EndpointMutualTLSMutate
`tls_termination`	EndpointTLSTermination

EndpointBackendMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

EndpointIPPolicyMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policy_ids`	List<string>	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLSMutate parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authority_ids`	List<string>	list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection

EndpointTLSTermination parameters


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Response

Returns a 200 response on success

Example Response

{
    "id": "edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "description": "acme tls edge",
    "metadata": "{\"environment\": \"production\"}",
    "created_at": "2023-07-31T23:17:45Z",
    "uri": "https://api.ngrok.com/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1",
    "hostports": ["example.com:443"],
    "backend": null,
    "ip_restriction": null,
    "mutual_tls": null,
    "tls_termination": null
}

Fields


`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields


`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref	list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields


`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Delete TLS Edge

Delete a TLS Edge by ID

Request

DELETE /edges/tls/{id}

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_2TMGJdBbx5IBRCRycI7hKUwANB1

Response

Returns a 204 response with no body on success

Edges TLS

Create TLS Edge​

Request​

Example Request​

Parameters​

EndpointBackendMutate parameters​

EndpointIPPolicyMutate parameters​

EndpointMutualTLSMutate parameters​

EndpointTLSTermination parameters​

Response​

Example Response​

Fields​

EndpointBackend fields​

Ref fields​

EndpointIPPolicy fields​

EndpointMutualTLS fields​

EndpointTLSTermination fields​

Get TLS Edge​

Request​

Example Request​

Response​

Example Response​

Fields​

EndpointBackend fields​

Ref fields​

EndpointIPPolicy fields​

EndpointMutualTLS fields​

EndpointTLSTermination fields​

List TLS Edges​

Request​

Example Request​

Response​

Example Response​

Fields​

TLSEdge fields​

EndpointBackend fields​

Ref fields​

EndpointIPPolicy fields​

EndpointMutualTLS fields​

EndpointTLSTermination fields​

Update TLS Edge​

Request​

Example Request​

Parameters​

EndpointBackendMutate parameters​

EndpointIPPolicyMutate parameters​

EndpointMutualTLSMutate parameters​

EndpointTLSTermination parameters​

Response​

Example Response​

Fields​

EndpointBackend fields​

Ref fields​

EndpointIPPolicy fields​

EndpointMutualTLS fields​

EndpointTLSTermination fields​

Delete TLS Edge​

Request​

Example Request​

Response​

Create TLS Edge

Request

Example Request

Parameters

EndpointBackendMutate parameters

EndpointIPPolicyMutate parameters

EndpointMutualTLSMutate parameters

EndpointTLSTermination parameters

Response

Example Response

Fields

EndpointBackend fields

Ref fields

EndpointIPPolicy fields

EndpointMutualTLS fields

EndpointTLSTermination fields

Get TLS Edge

Request

Example Request

Response

Example Response

Fields

EndpointBackend fields

Ref fields

EndpointIPPolicy fields

EndpointMutualTLS fields

EndpointTLSTermination fields

List TLS Edges

Request

Example Request

Response

Example Response

Fields

TLSEdge fields

EndpointBackend fields

Ref fields

EndpointIPPolicy fields

EndpointMutualTLS fields

EndpointTLSTermination fields

Update TLS Edge

Request

Example Request

Parameters

EndpointBackendMutate parameters

EndpointIPPolicyMutate parameters

EndpointMutualTLSMutate parameters

EndpointTLSTermination parameters

Response

Example Response

Fields

EndpointBackend fields

Ref fields

EndpointIPPolicy fields

EndpointMutualTLS fields

EndpointTLSTermination fields

Delete TLS Edge

Request

Example Request

Response