Skip to main content
TLS endpoints enable you to deliver any network service that runs over a TLS-based protocol. TLS endpoints make no assumptions about the wrapped protocol being transported. TLS endpoints inspect the Server Name Indication (SNI) data on incoming TLS connections to route connections to the appropriate endpoint. Because the TLS protocol describes no application-level semantics, ngrok can only offer a limited set of Traffic Policy actions to handle TLS traffic. If you are delivering an HTTPS application, prefer to create an HTTP Endpoint.

​
Quickstart

Cloud endpoints are persistent and live until they are deleted. They are created via the ngrok dashboard or API. Traffic Policy controls how a Cloud Endpoint handles traffic. See the Cloud Endpoints Quickstart for a step-by-step guide on how to create a Cloud Endpoint in the ngrok dashboard. The following example uses the API to create a Cloud Endpoint which returns a Hello world! 200 OK response.
Command line
traffic-policy.yml

​
URLs

ngrok validates URLs differently depending on their binding. Consult the following documentation for details on valid URLs for TLS endpoints: There is no standard scheme for TLS URLs, so ngrok renders them as tls://.

​
Bindings

TLS endpoints support public and internal bindings. They don’t support the kubernetes binding.

​
Traffic Policy

Attach Traffic Policy to endpoints to route, authenticate, and transform the traffic through your TLS endpoints.

​
Authentication

When you create public TLS endpoints, you often want to secure them with authentication. You can secure your TLS endpoints with the following Traffic Policy actions. There is a limited set of actions available to authenticate TLS traffic because the TLS protocol is low-level.

​
TLS termination

TLS Endpoints give you the flexibility to define where TLS termination occurs. You can configure your endpoint to terminate TLS at the ngrok cloud service, or you can achieve end-to-end encryption by terminating at the agent or your upstream service. When you use end-to-end encryption, the ngrok cloud service can’t see payloads that transit through your endpoints. Consult the documentation on TLS Termination Locations for additional details.

​
Example

To terminate TLS Cloud Endpoint traffic at an agent or an upstream service, you must create a Cloud Endpoint, then use the forward-internal action to forward traffic to an internal endpoint.
1

Create a TLS Cloud Endpoint

Create a TLS Cloud Endpoint in the dashboard, or with the following CLI command, adding your Traffic Policy file:
Command line
2

Create a Traffic Policy file

Create a Traffic Policy file to forward traffic to the internal endpoint, adding .internal to your domain for the URL. For example, if you’re using example.ngrok.dev, your internal endpoint URL should be tls://example.internal:
traffic-policy.yml
3

Create an internal endpoint

Create an internal endpoint using the same URL that your Traffic Policy references.
To learn more about terminating TLS at the agent, see the Agent Endpoint TLS documentation.

​
Certificates

It’s very common to encounter certificate errors when working with TLS endpoints. When terminating TLS at ngrok’s cloud service, ngrok automatically selects, provisions, and manages certs for you. When performing end-to-end encryption by terminating at the upstream service, you become responsible for provisioning, managing, and distributing certificates. Consult the documentation on TLS Certificates for details about certificate selection, provisioning, and management.

​
Compatible clients

​
SNI

TLS endpoints only work with modern TLS clients that populate the SNI extension. See the documentation on TLS Termination for additional details on compatible clients.

​
STARTTLS

ngrok doesn’t support protocols that begin in plain text and upgrade to TLS through a mechanism like STARTTLS in SMTP or IMAP. If you need to support connections that upgrade to TLS, use a TCP Endpoint.

​
Observability

​
Traffic Inspector

The TCP tab in Traffic Inspector lists each connection to your TLS endpoint after it closes, including client IP, TLS handshake details, bytes transferred, and any ngrok error.

​
Log exports

You can export logs of traffic to TLS endpoints with ngrok’s events system. ngrok publishes the following events for log exporting:

​
Limits & timeouts

Contact Support if you need to configure limits and timeouts on connections to TLS endpoints.

​
Connections

​
TLS

​
Errors

If a TLS handshake fails, ngrok sends an appropriate TLS abort code to the client. In all other cases, if ngrok encounters an error while handling TLS connections to your endpoints (for example, no available backends or an internal server error), it closes the connection. The TLS protocol and its implementations aren’t flexible enough to deliver additional rich error information when failures occur. Use the observability features to understand connection handling errors.

​
API

You can create TLS Endpoints programmatically. Consult the documentation on Endpoint APIs.

​
TLS Cloud Endpoint pricing

TLS endpoints are available on Hobbyist and Pay-as-you-go plans. Consult the pricing documentation for billing details. See Domains pricing for details on pricing for custom domains, wildcard endpoints, and more. Zero-knowledge TLS is available on the Pay-as-you-go plan.