> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TLS Cloud Endpoints

> Learn how to create and configure TLS endpoints with ngrok for handling encrypted TLS traffic using SNI-based routing.

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)](#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](/traffic-policy/actions/)
to handle TLS traffic.

If you are delivering an HTTPS application, prefer to create an [HTTP
Endpoint](/gateway/http/).

## Quickstart

[Cloud endpoints](/gateway/cloud-endpoints/) are persistent and live until they are
deleted.
They are created via [the
ngrok Dashboard](https://dashboard.ngrok.com/endpoints/new) or [API](/api/). [Traffic Policy](/traffic-policy/) controls how a Cloud Endpoint
handles traffic.

See the [Cloud Endpoints Quickstart](/getting-started/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.

```bash title="Command line" theme={null}
ngrok api endpoints create \
	--url tls://{your-domain-here}.ngrok-free.dev \
	--traffic-policy "$(<traffic-policy.yml)"
```

```yaml title="traffic-policy.yml" mode=traffic-policy theme={null}
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](/gateway/bindings). Consult the
following documentation for details on valid URLs for TLS endpoints:

* [Public Endpoint URLs](/gateway/public-endpoints/#https-tls)
* [Internal Endpoint URLs](/gateway/internal-endpoints/#urls)
* [Kubernetes Endpoint URLs](/gateway/kubernetes-endpoints/#urls)

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](/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](/traffic-policy/) actions. There is a limited set of actions available
to authenticate TLS traffic because the TLS protocol is low-level.

* [IP Restriction](/traffic-policy/actions/restrict-ips/)
* [Mutual TLS](/traffic-policy/actions/terminate-tls/)

## 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](/gateway/tls-termination/#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](/gateway/tls-termination/#termination-location) 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`](/traffic-policy/actions/forward-internal/) action to forward traffic to an internal endpoint.

1. Create a TLS Cloud Endpoint [in the dashboard](https://dashboard.ngrok.com/endpoints/new), or with the following CLI command, adding your Traffic Policy file:
   ```bash title="Command line" theme={null}
   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`:
   ```yaml title="traffic-policy.yml" mode=traffic-policy theme={null}
   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.

   <Tabs>
     <Tab title="At the upstream">
       ```bash theme={null}
       ngrok tls {your-port-here} \
       --terminate-at upstream \
       --url tls://{your-domain-here}.internal \
       --binding internal
       ```
     </Tab>

     <Tab title="At the Agent">
       ```bash theme={null}
       ngrok tls 80 \
       --terminate-at agent \
       --binding internal \
       --url example.internal \
       --crt /path/to/app-example-com-crt.pem \
       --key /path/to/app-example-com-key.pem
       ```
     </Tab>
   </Tabs>

To learn more about terminating TLS at the agent, see the [Agent Endpoint TLS documentation](/gateway/tls#termination).

### 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](/gateway/tls-termination/#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](/gateway/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](/gateway/tls-termination/#sni) 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](/gateway/tcp/).

## Observability

### Traffic Inspector

[Traffic Inspector](/obs/traffic-inspection) does not support TLS endpoints.

### Log exports

You can export logs of traffic to TLS endpoints with [ngrok's events
system](/obs/). The following events are published for log exporting:

| Log                                                                        | When                                                         |
| -------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [tcp\_connection\_closed.v0](/obs/events/reference/#tcp-connection-closed) | Published when a TCP connection to a TCP endpoint completes. |

## Limits & timeouts

[Contact Support](mailto:support@ngrok.com) if you need to configure limits and
timeouts on connections to TLS endpoints.

### Connections

| Limit     | Name                | Notes                                                          |
| --------- | ------------------- | -------------------------------------------------------------- |
| 3 seconds | ClientHello Timeout | Time between connection establishment and ClientHello received |
| 5 minutes | Client Idle Timeout | Time since data was last transmitted by the upstream service   |
| 5 minutes | Server Idle Timeout | Time since data was last transmitted by the upstream service   |
| No limit  | Data transmitted    | Data transmitted by the client or upstream service             |

### TLS

<TlsLimits />

## 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](#observability) features to understand connection
handling errors.

## API

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

## TLS Cloud Endpoint pricing

TLS endpoints are available on Hobbyist and Pay-as-you-go plans. Consult the [pricing](/pricing-limits/#endpoint-limits) documentation for
billing details.

See [Domains pricing](/gateway/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.