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

# HTTP/S Cloud Endpoints

> Learn how to create and configure HTTP and HTTPS endpoints with ngrok including domain configuration, TLS, and Traffic Policies.

HTTP/S endpoints enable you to serve web services like REST APIs, web applications, websites, and WebSocket servers.
Serving a web application is as simple as `ngrok http 80`.

Once your endpoint is running, check out:

* [Traffic Policy](/traffic-policy/) - Add routing, authentication and traffic transformation
* [Traffic Inspector](https://dashboard.ngrok.com/traffic-inspection/) - Real-time observability with request/response introspection
* [Endpoint Pooling](/gateway/endpoint-pooling/) - Load balancing

## 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 https://{your-domain-here}.ngrok.app \
  --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!"
```

## URL

URLs are validated differently depending on their
[binding](/gateway/bindings). Consult the
following documentation for details on valid URLs for TCP endpoints:

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

### Public

#### HTTP

* The hostname must be a domain with a valid [public suffix](https://publicsuffix.org/).
* The port must be `80`. If you do not specify a port, the default `80` will be used for you.

**Examples**

* `http://example.ngrok.app`
* `http://example.ngrok.app:80`
* `http://example.party`
* `http://example.ngrok.app:81` - invalid port: port number must be `80`, not `81`
* `http://example.doesnotexist` - invalid hostname: `.doesnotexist` is not a public suffix domain
* `http://example.internal` - invalid hostname: `.internal` is not a public suffix domain

#### HTTPS

* The hostname must be a domain with a valid [public suffix](https://publicsuffix.org/).
* The port must be `443`. If you do not specify a port, the default `443` will be used for you.

#### Internal

#### Kubernetes

##### Valid URLs

* [https://example.ngrok.app](https://example.ngrok.app)
* [https://example.ngrok.app:443](https://example.ngrok.app:443)
* [https://example.party](https://example.party)

#### Invalid URLs

* [https://example.ngrok.app:8443](https://example.ngrok.app:8443)
* [https://example.nosuchtld](https://example.nosuchtld)
* [https://example.internal](https://example.internal)

### Validation

When you create a
Cloud Endpoint, you must always specify both a scheme and hostname.

If you would like to listen for both http and https traffic, create two endpoints.

#### Domains

When you create a public endpoint, it must match a
[Domain](/gateway/domains) on your account. Domains help you set up
branded domains and manage TLS certificates. You may create wildcard endpoints as well.

Endpoints with randomly assigned hostnames are an exception and won't match an
existing Domain object.

### Bring your own domain

If you want to bring your own domain, first [create a Domain record and set up
a DNS CNAME record](/gateway/domains/#branded-domains). Then
create an endpoint on that domain by specifying a URL with a matching hostname.

For example, to create an HTTPS endpoint on `https://app.example.com`, [create
a Domain](https://dashboard.ngrok.com/domains) and follow the instructions to
set up a CNAME record. Then create a [Cloud Endpoint](https://dashboard.ngrok.com/endpoints/new) in the dashboard or use the following example to start an endpoint on
your domain

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

### Wildcard endpoints

You can create a wildcard endpoint which will receive traffic for all of the subdomains
matching a wildcard pattern like `*.example.com`. To create a public wildcard endpoint, you must first reserve a [wildcard domain](/gateway/domains/#wildcard-domains).

For example, if you create the wildcard endpoint `https://*.example.com`, it
will receive traffic for `https://foo.example.com` and
`https://bar.example.com`.

* Connections to URLs which match an online wildcard endpoint will be routed to
  it. For example, if you have created a wildcard endpoint
  `https://*.example.com`, connections to `https://foo.bar.baz.example.com` will
  route to it.
* Connections are routed to the most specific online endpoint. For example, if
  the endpoints `https://*.example.com` and `https://app.example.com` are both
  online, a connection to `https://app.example.com` will not be routed to the
  wildcard endpoint.

You can create a Cloud Endpoint with a Wildcard domain in the [ngrok dashboard](https://dashboard.ngrok.com/endpoints/new/cloud), or with the following terminal command:

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

<Note>
  For information on how wildcard endpoints are billed, including endpoint hours and Traffic Policy charges when forwarding to internal endpoints, see the [wildcard endpoints pricing documentation](/pricing-limits/#wildcard-endpoints).
</Note>

## Traffic Policy

Attach [Traffic Policy](/traffic-policy/) to endpoints to route, authenticate and transform the traffic through the endpoint.

### Authentication

Public endpoints are accessible to the public internet unless you secure them
with authentication. That's desirable if you're hosting a public website but
most often you want to add authentication. You can secure your endpoints with
[Traffic Policy](/traffic-policy) with any of the following actions:

* [Basic Auth](/traffic-policy/actions/basic-auth)
* [OAuth](/traffic-policy/actions/oauth)
* [IP Restriction](/traffic-policy/actions/restrict-ips/)
* [Webhook Verification](/traffic-policy/actions/verify-webhook/)
* [JWT](/traffic-policy/actions/jwt-validation/)
* [Mutual TLS](/traffic-policy/actions/terminate-tls/)
* [OpenID Connect](/traffic-policy/actions/oidc/)
* [SAML](/traffic-policy/actions/saml/)

#### Basic auth example

Adds a username and password with the [Basic
Auth](/traffic-policy/actions/basic-auth) Traffic Policy action.

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_http_request:
    - actions:
      - type: "basic-auth"
        config:
          realm: "sample-realm"
          credentials:
            - "user:password1"
            - "admin:password2"
          enforce: true
      - type: "custom-response"
        config:
          status_code: 200
          headers:
            content-type: "text/plain"
          body: "Successfully Authenticated!"
  ```

  ```json policy.json theme={null}
  {
    "on_http_request": [
      {
        "actions": [
          {
            "type": "basic-auth",
            "config": {
              "realm": "sample-realm",
              "credentials": [
                "user:password1",
                "admin:password2"
              ],
              "enforce": true
            }
          },
          {
            "type": "custom-response",
            "config": {
              "status_code": 200,
              "headers": {
                "content-type": "text/plain"
              },
              "body": "Successfully Authenticated!"
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

<br />

#### Google OAuth example

The following example enforces a browser-based OAuth redirect flow in front of
your endpoint using Google as the identity provider by using the
[OAuth](/traffic-policy/actions/oauth) Traffic Policy action.

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_http_request:
    - actions:
        - type: oauth
          config:
            provider: google
  ```

  ```json policy.json theme={null}
  {
    "on_http_request": [
      {
        "actions": [
          {
            "type": "oauth",
            "config": {
              "provider": "google"
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

The `provider` value can be replaced with any of the [Supported Providers](/traffic-policy/actions/oauth/#supported-providers) that have an
a managed app available.

#### Rewriting the `host` header

Some application servers expect the `host` header to match a specific value
when they receive requests and some use the `host` header to determine which of
many sites to display. ngrok can rewrite the `host` header of incoming requests
so that your application behaves correctly.

When you rewrite the `host` header, ngrok also rewrites the `location` header of
HTTP responses automatically to match the hostname of your Endpoint URL.

The following example rewrites the `host` header to the value `localhost` using
the [`add-headers`](/traffic-policy/actions/add-headers) Traffic Policy action.
Adding the `Host` header [is a special
case](/traffic-policy/actions/add-headers/#special-cases) that replaces the existing
`Host` header instead of appending a second value.

<CodeGroup>
  ```yaml policy.yml theme={null}
  on_http_request:
    - actions:
        - type: add-headers
          config:
            headers:
              host: localhost
  ```

  ```json policy.json theme={null}
  {
    "on_http_request": [
      {
        "actions": [
          {
            "type": "add-headers",
            "config": {
              "headers": {
                "host": "localhost"
              }
            }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

## Traffic observability

### Traffic Inspector

[Traffic Inspector](/obs/traffic-inspection/) gives you a real-time view in the
ngrok dashboard of the HTTP traffic flowing through your HTTP/S endpoints. You
can choose whether Traffic Inspector captures only request metadata or full
request and response bodies.

### Log export logs

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

| Log                                                                        | When                                                              |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [http\_request\_complete.v0](/obs/events/reference/#http-request-complete) | Published when an HTTP request to an HTTP/S endpoints completes.  |
| [tcp\_connection\_closed.v0](/obs/events/reference/#tcp-connection-closed) | Published when a TCP connection to an HTTP/S endpoints completes. |

## Advanced

HTTP/S endpoints are standards-compliant HTTP reverse proxies.

### Versions

* HTTP/S endpoints support HTTP/1.1.
* HTTPS endpoints support HTTP/1.1 and HTTP/2.
* HTTP/1.0, HTTP/3 and QUIC are **not** supported.

### HTTP/2

HTTPS endpoints will automatically use HTTP/2 for all connections if the client
supports it. Client support is determined via standard ALPN negotiation.

HTTP/2 is used between the client and your endpoint even even if your upstream
service does not support HTTP/2.

To configure the use of HTTP/2 when sending traffic to an upstream service, consider [using an Agent Endpoint](/gateway/http/#http2-forwarding).

### WebSockets

WebSocket connections are supported out-of-the-box. No configuration is required.

### Hop by hop headers

ngrok does not forward any [hop-by-hop
headers](https://datatracker.ietf.org/doc/html/rfc2616#section-13.5.1) to the
upstream service. As an exception, `Connection: upgrade` headers are forwarded
to support [websockets](#websockets).

For information on headers added automatically by ngrok, see
[Upstream Headers](#upstream-headers).

### Persistent connections

When a connection is made to HTTP/S ngrok endpoints with HTTP/1.1, ngrok may
choose to use persistent connections (such as HTTP keep-alive) to improve the
performance of future requests from the same client if the client supports it.

This behavior is not guaranteed and it is not configurable.

See [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230#section-6.3) for
additional details.

### Well known URIs

#### `/.well-known/acme-challenge`

ngrok takes over handling of this path of any HTTP endpoint matching a
[Domain](/gateway/domains) with automated certificate management
enabled. You may disable this behavior by uploading your own certificate on the
matching Domain.

## TLS

ngrok automatically handles TLS (SSL) certificate management and termination for you.
There is nothing to set up, configure, or manage.

TLS connections to `https` endpoints are terminated at ngrok's cloud service.
If you wish to terminate TLS traffic at the ngrok cloud service or in your upstream
application, use a [TLS Endpoint](/gateway/tls) instead.

Consult the following documentation for additional details on how ngrok handles
TLS termination and certificiate management:

* [TLS Certificates](/gateway/tls-certificates)
* [TLS Termination](/gateway/tls-termination)

## Upstream headers

ngrok adds headers to each HTTP request with information about the original
client IP, request scheme and request `host` header value.

| Header              | Description                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-forwarded-for`   | The IP address of the client who initiated the request. If this header exists on the original request, ngrok will append a new value.       |
| `x-forwarded-proto` | The scheme of the original request, either `http` or `https`. If this header exists on the original request, ngrok will append a new value. |
| `x-forwarded-host`  | The header from the client's request if it existed, otherwise is set to the request's `Host` header value.                                  |

Because ngrok appends values to `x-forwarded-for` and `x-forwarded-proto`, be
sure to use the last value of the header in your application code to read the
values injected by ngrok.

You may remove these headers with the [Remove
Headers](/traffic-policy/actions/remove-headers/) Traffic Policy action.

## Limits & timeouts

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

#### Connection

| Limit     | Name                | Notes                                                        |
| --------- | ------------------- | ------------------------------------------------------------ |
| 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 />

#### HTTP

| Limit      | Name               | Notes                                         |
| ---------- | ------------------ | --------------------------------------------- |
| No timeout | Round Trip Timeout | Time for the entire HTTP request and response |

### HTTP request

| Limit      | Name                   | Notes                                                |
| ---------- | ---------------------- | ---------------------------------------------------- |
| 1 MB       | Request Header Size    | Includes method, URI, and headers                    |
| 1 MB       | Request URI Length     | Limited by the size of the request header            |
| No timeout | Request Timeout        | Time to read the entire HTTP request from the client |
| No timeout | Request Header Timeout | Time to read the HTTP request header from the client |
| No limit   | Request Body Size      |                                                      |

#### HTTP response

| Limit      | Name                    | Notes                                                 |
| ---------- | ----------------------- | ----------------------------------------------------- |
| 1 MB       | Response Header Size    | Includes method, URI, and headers                     |
| No timeout | Response Timeout        | Time to read the entire HTTP response from the server |
| No timeout | Response Header Timeout | Time to read the HTTP response header from the server |
| No limit   | Response Body Size      |                                                       |

## Errors

If ngrok fails to handle an HTTP request it will set the `ngrok-error-code`
header in the HTTP response with a [unique ngrok Error Code](/errors/)
describing the failure.

ngrok guarantees that the upstream service may never set the `ngrok-error-code`
HTTP response header so you know reliably that it was set by ngrok.

ngrok may return an error under the following conditions:

* Your upstream service timed out or rejected the connection
* Your upstream service returned a response that was not valid HTTP
* A [Traffic Policy](/traffic-policy) action rejected the request.
* [Traffic Policy](/traffic-policy) execution encountered a runtime error.
* ngrok encountered an internal error

## API

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

## HTTP Cloud Endpoint pricing

HTTP/S endpoints are available on all plans. Consult the [Endpoints
Pricing](/gateway/endpoints/#pricing) documentation for
billing details.

See [Domains pricing](/gateway/domains/#pricing) for details on
pricing for custom domains, wildcard endpoints and more.