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-06-14T06:04:03Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C"
}
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_2hrGzJJS2OYwnm9Wi8uZanXLN1C
Response
Returns a 200 response on success
Example Response
{
"backend": null,
"created_at": "2024-06-14T06:04:03Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C"
}
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-06-14T06:04:03Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C"
},
{
"backend": {
"backend": {
"id": "bkdhr_2hrGy2yLoXBeB6HmeNdR4g49TNd",
"uri": "https://api.ngrok.com/backends/http_response/bkdhr_2hrGy2yLoXBeB6HmeNdR4g49TNd"
},
"enabled": true
},
"created_at": "2024-06-14T06:03:53Z",
"description": "acme tls edge",
"hostports": ["endpoint-example2.com:443"],
"id": "edgtls_2hrGy7Nc38eVlDViZ7IMsyDNUNa",
"ip_restriction": null,
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2hrGy7Nc38eVlDViZ7IMsyDNUNa"
}
],
"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_2hrGzJJS2OYwnm9Wi8uZanXLN1C
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-06-14T06:04:03Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C",
"ip_restriction": null,
"metadata": "{\"environment\": \"production\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2hrGzJJS2OYwnm9Wi8uZanXLN1C"
}
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_2hrGzJJS2OYwnm9Wi8uZanXLN1C
Response
Returns a 204 response with no body on success