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","hostports":["example.com:443"],"metadata":"{\"environment\": \"staging\"}"}' \
https://api.ngrok.com/edges/tls

Parameters

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackendMutate parameters

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy parameters

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule parameters

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction parameters

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

Response

Returns a 201 response on success

Example Response

{
	"backend": null,
	"created_at": "2024-02-16T19:35:36Z",
	"description": "acme tls edge",
	"hostports": ["example.com:443"],
	"id": "edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l",
	"ip_restriction": null,
	"metadata": "{\"environment\": \"staging\"}",
	"mutual_tls": null,
	"policy": null,
	"tls_termination": null,
	"uri": "https://api.ngrok.com/edges/tls/edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l"
}

Fields

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackend fields

Name	Type	Description
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

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

EndpointIPPolicy fields

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule fields

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction fields

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

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_2cSjzX6pa6EUuGOEOtztSMqPK6l

Response

Returns a 200 response on success

Example Response

{
	"backend": null,
	"created_at": "2024-02-16T19:35:36Z",
	"description": "acme tls edge",
	"hostports": ["example.com:443"],
	"id": "edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l",
	"ip_restriction": null,
	"metadata": "{\"environment\": \"staging\"}",
	"mutual_tls": null,
	"policy": null,
	"tls_termination": null,
	"uri": "https://api.ngrok.com/edges/tls/edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l"
}

Fields

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackend fields

Name	Type	Description
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

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

EndpointIPPolicy fields

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule fields

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction fields

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

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

{
	"next_page_uri": null,
	"tls_edges": [
		{
			"backend": null,
			"created_at": "2024-02-16T19:35:36Z",
			"description": "acme tls edge",
			"hostports": ["example.com:443"],
			"id": "edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l",
			"ip_restriction": null,
			"metadata": "{\"environment\": \"staging\"}",
			"mutual_tls": null,
			"policy": null,
			"tls_termination": null,
			"uri": "https://api.ngrok.com/edges/tls/edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l"
		},
		{
			"backend": {
				"backend": {
					"id": "bkdhr_2cSjyGQKTgGPdD7IHYSLPwTnIxm",
					"uri": "https://api.ngrok.com/backends/http_response/bkdhr_2cSjyGQKTgGPdD7IHYSLPwTnIxm"
				},
				"enabled": true
			},
			"created_at": "2024-02-16T19:35:26Z",
			"description": "acme tls edge",
			"hostports": ["endpoint-example2.com:443"],
			"id": "edgtls_2cSjyGeNROACDCqWqgVKmVny8Qj",
			"ip_restriction": null,
			"mutual_tls": null,
			"policy": null,
			"tls_termination": null,
			"uri": "https://api.ngrok.com/edges/tls/edgtls_2cSjyGeNROACDCqWqgVKmVny8Qj"
		}
	],
	"uri": "https://api.ngrok.com/edges/tls"
}

Fields

Name	Type	Description
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

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackend fields

Name	Type	Description
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

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

EndpointIPPolicy fields

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule fields

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction fields

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

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_2cSjzX6pa6EUuGOEOtztSMqPK6l

Parameters

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackendMutate parameters

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy parameters

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule parameters

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction parameters

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

Response

Returns a 200 response on success

Example Response

{
	"backend": null,
	"created_at": "2024-02-16T19:35:36Z",
	"description": "acme tls edge",
	"hostports": ["example.com:443"],
	"id": "edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l",
	"ip_restriction": null,
	"metadata": "{\"environment\": \"production\"}",
	"mutual_tls": null,
	"policy": null,
	"tls_termination": null,
	"uri": "https://api.ngrok.com/edges/tls/edgtls_2cSjzX6pa6EUuGOEOtztSMqPK6l"
}

Fields

Name	Type	Description
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
policy	EndpointPolicy	the traffic policy associated with this edge or null

EndpointBackend fields

Name	Type	Description
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

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

EndpointIPPolicy fields

Name	Type	Description
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

Name	Type	Description
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

Name	Type	Description
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.

EndpointPolicy fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
inbound	EndpointRule	the inbound rules of the traffic policy.
outbound	EndpointRule	the outbound rules on the traffic policy.

EndpointRule fields

Name	Type	Description
expressions	List<string>	cel expressions that filter traffic the policy rule applies to.
actions	EndpointAction	the set of actions on a policy rule.
name	string	the name of the rule that is part of the traffic policy.

EndpointAction fields

Name	Type	Description
type	string	the type of action on the policy rule.
config	object	the configuration for the action on the policy rule.

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_2cSjzX6pa6EUuGOEOtztSMqPK6l

Response

Returns a 204 response with no body on success