HTTP/S Cloud Endpoints - ngrok documentation

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 - Add routing, authentication and traffic transformation
Traffic Inspector - Real-time observability with request/response introspection
Endpoint Pooling - Load balancing

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

URL

ngrok validates URLs differently depending on their binding. Consult the following documentation for details on valid URLs for HTTP endpoints:

Public

HTTP

The hostname must be a domain with a valid public suffix.
The port must be 80. If you don’t specify a port, ngrok uses the default 80 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.
The port must be 443. If you don’t specify a port, ngrok uses the default 443 for you.

Valid URLs

Invalid URLs

Validation

When you create a Cloud Endpoint, you must always specify both a scheme and hostname. To listen for both HTTP and HTTPS traffic, create two endpoints.

Domains

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

Bring your own domain

To bring your own domain, first create a Domain record and set up a DNS CNAME record. 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 and follow the instructions to set up a CNAME record. Then create a Cloud Endpoint in the dashboard or use the following example to start an endpoint on your domain:

Command line

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 receives 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. For example, if you create the wildcard endpoint https://*.example.com, it receives traffic for https://foo.example.com and https://bar.example.com.

Connections to URLs which match an online wildcard endpoint are routed to it. For example, if you have created a wildcard endpoint https://*.example.com, connections to https://foo.bar.baz.example.com 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 isn’t routed to the wildcard endpoint.

You can create a Cloud Endpoint with a wildcard domain in the ngrok dashboard, or with the following terminal command:

Command line

ngrok api endpoints create \
  --url https://*.{your-domain-here}.ngrok.app \
  --traffic-policy "$(<traffic-policy.yml)"

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.

Traffic Policy

Attach 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 with any of the following actions:

Basic auth example

The following example adds a username and password with the Basic Auth Traffic Policy action.

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!"

{
  "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!"
          }
        }
      ]
    }
  ]
}

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

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "oauth",
          "config": {
            "provider": "google"
          }
        }
      ]
    }
  ]
}

You can replace the provider value with any of the Supported Providers that have 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 action. Adding the Host header is a special case that replaces the existing Host header instead of appending a second value.

on_http_request:
  - actions:
      - type: add-headers
        config:
          headers:
            host: localhost

{
  "on_http_request": [
    {
      "actions": [
        {
          "type": "add-headers",
          "config": {
            "headers": {
              "host": "localhost"
            }
          }
        }
      ]
    }
  ]
}

Traffic observability

Traffic Inspector

Traffic Inspector 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. ngrok publishes the following events for log exporting:

Log	When
http_request_complete.v0	Published when an HTTP request to an HTTP/S endpoints completes.
tcp_connection_closed.v0	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 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 if your upstream service doesn’t support HTTP/2. To configure the use of HTTP/2 when sending traffic to an upstream service, consider using an Agent Endpoint.

WebSockets

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

Hop by hop headers

ngrok doesn’t forward any hop-by-hop headers to the upstream service. As an exception, ngrok forwards Connection: upgrade headers to support WebSockets. For information on headers added automatically by ngrok, see 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 isn’t guaranteed and it isn’t configurable. See RFC 7230 for additional details.

Well known URIs

`/.well-known/acme-challenge`

ngrok takes over handling of this path of any HTTP endpoint matching a Domain 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 instead. Consult the following documentation for additional details on how ngrok handles TLS termination and certificate management:

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 appends 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 appends 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 action.

Limits & timeouts

Contact Support 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

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 sets the ngrok-error-code header in the HTTP response with a unique ngrok Error Code 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 wasn’t valid HTTP.
A Traffic Policy action rejected the request.
Traffic Policy execution encountered a runtime error.
ngrok encountered an internal error.

API

You can create HTTP/S Endpoints 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 documentation for billing details. See Domains pricing for details on pricing for custom domains, wildcard endpoints, and more.

​Quickstart

​URL

​Public

​HTTP

​HTTPS

​Validation

​Domains

​Bring your own domain

​Wildcard endpoints

​Traffic Policy

​Authentication

​Basic auth example

​Google OAuth example

​Rewriting the host header

​Traffic observability

​Traffic Inspector

​Log export logs

​Advanced

​Versions

​HTTP/2

​WebSockets

​Hop by hop headers

​Persistent connections

​Well known URIs

​/.well-known/acme-challenge

​TLS

​Upstream headers

​Limits & timeouts

​Connection

​TLS

​HTTP

​HTTP request

​HTTP response

​Errors

​API

​HTTP Cloud Endpoint pricing

Quickstart

URL

Public

HTTP

HTTPS

Validation

Domains

Bring your own domain

Wildcard endpoints

Traffic Policy

Authentication

Basic auth example

Google OAuth example

Rewriting the `host` header

Traffic observability

Traffic Inspector

Log export logs

Advanced

Versions

HTTP/2

WebSockets

Hop by hop headers

Persistent connections

Well known URIs

`/.well-known/acme-challenge`

TLS

Upstream headers

Limits & timeouts

Connection

TLS

HTTP

HTTP request

HTTP response

Errors

API

HTTP Cloud Endpoint pricing