Skip to main content

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

NameTypeDescription
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
hostportsList<string>hostports served by this edge
backendEndpointBackendMutateedge modules
ip_restrictionEndpointIPPolicyMutate
mutual_tlsEndpointMutualTLSMutate
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackendMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backend_idstringbackend to be used to back this endpoint

EndpointIPPolicyMutate parameters

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

EndpointMutualTLSMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authority_idsList<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

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

Response

Returns a 201 response on success

Example Response

{
"backend": null,
"created_at": "2024-08-02T07:15:43Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2k5okm080IjPkDFFABCDEajMWvP",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"traffic_policy": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2k5okm080IjPkDFFABCDEajMWvP"
}

Fields

NameTypeDescription
idstringunique identifier of this edge
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
uristringURI of the edge API resource
hostportsList<string>hostports served by this edge
backendEndpointBackendedge modules
ip_restrictionEndpointIPPolicy
mutual_tlsEndpointMutualTLS
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authoritiesRefPEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

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_2k5okm080IjPkDFFABCDEajMWvP

Response

Returns a 200 response on success

Example Response

{
"backend": null,
"created_at": "2024-08-02T07:15:43Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2k5okm080IjPkDFFABCDEajMWvP",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"traffic_policy": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2k5okm080IjPkDFFABCDEajMWvP"
}

Fields

NameTypeDescription
idstringunique identifier of this edge
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
uristringURI of the edge API resource
hostportsList<string>hostports served by this edge
backendEndpointBackendedge modules
ip_restrictionEndpointIPPolicy
mutual_tlsEndpointMutualTLS
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authoritiesRefPEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

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-08-02T07:15:43Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2k5okm080IjPkDFFABCDEajMWvP",
"ip_restriction": null,
"metadata": "{\"environment\": \"staging\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"traffic_policy": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2k5okm080IjPkDFFABCDEajMWvP"
},
{
"backend": {
"backend": {
"id": "bkdhr_2k5ojPH2ojjAu2xs3QuOj4tvrEf",
"uri": "https://api.ngrok.com/backends/http_response/bkdhr_2k5ojPH2ojjAu2xs3QuOj4tvrEf"
},
"enabled": true
},
"created_at": "2024-08-02T07:15:32Z",
"description": "acme tls edge",
"hostports": ["endpoint-example2.com:443"],
"id": "edgtls_2k5ojMmZRNYMInd6d6ZxOFrymH0",
"ip_restriction": null,
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"traffic_policy": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2k5ojMmZRNYMInd6d6ZxOFrymH0"
}
],
"uri": "https://api.ngrok.com/edges/tls"
}

Fields

NameTypeDescription
tls_edgesTLSEdgethe list of all TLS Edges on this account
uristringURI of the TLS Edge list API resource
next_page_uristringURI of the next page, or null if there is no next page

TLSEdge fields

NameTypeDescription
idstringunique identifier of this edge
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
uristringURI of the edge API resource
hostportsList<string>hostports served by this edge
backendEndpointBackendedge modules
ip_restrictionEndpointIPPolicy
mutual_tlsEndpointMutualTLS
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authoritiesRefPEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

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_2k5okm080IjPkDFFABCDEajMWvP

Parameters

NameTypeDescription
idstringunique identifier of this edge
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
hostportsList<string>hostports served by this edge
backendEndpointBackendMutateedge modules
ip_restrictionEndpointIPPolicyMutate
mutual_tlsEndpointMutualTLSMutate
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackendMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backend_idstringbackend to be used to back this endpoint

EndpointIPPolicyMutate parameters

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

EndpointMutualTLSMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authority_idsList<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

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

Response

Returns a 200 response on success

Example Response

{
"backend": null,
"created_at": "2024-08-02T07:15:43Z",
"description": "acme tls edge",
"hostports": ["example.com:443"],
"id": "edgtls_2k5okm080IjPkDFFABCDEajMWvP",
"ip_restriction": null,
"metadata": "{\"environment\": \"production\"}",
"mutual_tls": null,
"policy": null,
"tls_termination": null,
"traffic_policy": null,
"uri": "https://api.ngrok.com/edges/tls/edgtls_2k5okm080IjPkDFFABCDEajMWvP"
}

Fields

NameTypeDescription
idstringunique identifier of this edge
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
uristringURI of the edge API resource
hostportsList<string>hostports served by this edge
backendEndpointBackendedge modules
ip_restrictionEndpointIPPolicy
mutual_tlsEndpointMutualTLS
tls_terminationEndpointTLSTermination
traffic_policyEndpointTrafficPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLS fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authoritiesRefPEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
terminate_atstringedge 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_versionstringThe 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.

EndpointTrafficPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
valuestringthe traffic policy that should be applied to the traffic on your endpoint.

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_2k5okm080IjPkDFFABCDEajMWvP

Response

Returns a 204 response with no body on success