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
ngrok api endpoints create \
	--url tls://{your-domain-here}.ngrok-free.dev \
	--traffic-policy "$(<traffic-policy.yml)"
traffic-policy.yml
on_http_request:
- actions:
  - type: custom-response
    config:
      status_code: 200
      headers:
        content-type: text/plain
      body: "Hello world!"

​
URLs

URLs are validated 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. kubernetes binding is not supported.

​
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 provide you with the flexibility to define where TLS termination occurs. You may 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 not see payload 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 in the dashboard, or with the following CLI command, adding your Traffic Policy file:
    Command line
    ngrok api endpoints create \
	--url tls://{your-domain-here}.com \
	--traffic-policy "$(<traffic-policy.yml)"
  2. 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
    on_tcp_connect:
  - actions:
      - type: forward-internal
        config:
          url: tls://{your-domain-here}.internal:{your-port-here}
  3. Create an internal endpoint using the same url that your Traffic Policy references. 
    ngrok tls {your-port-here} \
--terminate-at upstream \
--url tls://{your-domain-here}.internal \
--binding internal
To learn more about terminating TLS at the agent, see the Agent Endpoint TLS documentation.

​
Certificates

It is very common to encounter certificate errors when working with TLS endpoints. When terminating TLS at ngrok’s cloud service, ngrok will automatically select, provision, and manage 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

Protocols that begin in plain text and upgrade to TLS via a mechanism like STARTTLS in SMTP, IMAP, etc are not supported. If you need to support connections which upgrade to TLS, use a TCP Endpoint.

​
Observability

​
Traffic Inspector

Traffic Inspector does not support TLS endpoints.

​
Log exports

You can export logs of traffic to TLS endpoints with ngrok’s events system. The following events are published for log exporting:
LogWhen
tcp_connection_closed.v0Published when a TCP connection to a TCP endpoint completes.

​
Limits & timeouts

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

​
Connections

LimitNameNotes
3 secondsClientHello TimeoutTime between connection establishment and ClientHello received
5 minutesClient Idle TimeoutTime since data was last transmitted by the upstream service
5 minutesServer Idle TimeoutTime since data was last transmitted by the upstream service
No limitData transmittedData transmitted by the client or upstream service

​
TLS

​
Errors

If a TLS handshake fails, an appropriate TLS abort code will be sent to the client. In all other cases, if an error is encountered while handling TLS connections to your endpoints (for example, no available backends or internal server error), the connection will be closed. The TLS protocol and its implementations are not sufficiently flexible enough to deliver additional rich error information when failures are encountered. Use the observability features to understand connection handling errors.

​
API

TLS Endpoints can be created programmatically. Consult the documentation on [Endpoint APIs](/api-reference/endpoints/list.

​
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.