Skip to main content

HTTP/S Endpoints

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:

Quickstart​

Agent Endpoint​

Agent Endpoints are the easiest way to get started with ngrok. An agent endpoint is started by a Secure Tunnels agent. The endpoint lives for the lifetime of the process and forwards traffic to a port or URL of your choosing.

Create the endpoint https://example.ngrok.app and forward its traffic to a local port.

Loading…

Cloud Endpoint​

Cloud endpoints are created via the ngrok Dashboard or API. They are persistent and live until they are deleted. Traffic Policy controls how a cloud endpoint handles traffic.

Create an HTTPS cloud endpoint which returns a Hello world! 200 OK response.

Loading…
Loading…

URL​

URLs are validated differently depending on their binding. Consult the following documentation for details on valid URLs for TCP endpoints:

Public​

HTTP​
  • The hostname must be a domain with a valid public suffix.
  • 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.
  • The port must be 443. If you do not specify a port, the default 443 will be used for you.

Internal​

Kubernetes​

Valid URLs​
Invalid URLs​

Validation​

When you create an agent endpoint, if you do not specify a complete URL, following defaults are used to construct an endpoint URL. When you create a cloud endpoint, you must always specify both a scheme and hostname.

URL PartDefault
Schemehttps
Hostnamerandomly selected
Port443 if scheme is https
80 if scheme is http

Consult the following table of examples of URL defaulting:

ValueEndpoint URL
https://example.ngrok.apphttps://example.ngrok.app
http://example.ngrok.apphttp://example.ngrok.app
example.ngrok.apphttps://example.ngrok.app
app.example.comhttps://app.example.com
https://example.internalhttps://example.internal
https://example.internal:1234https://example.internal:1234
http://example.internalhttp://example.internal
foo.internalhttps://foo.internal
{empty}https://1eb2-181-80-12-3.ngrok.app (randomly selected)

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 on your account. Domains help you set up branded domains and manage TLS certificates. You may create endpoints with wildcard domains 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. 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 use the following example to start an endpoint on your domain:

Loading…

Wildcard endpoints​

You can create an endpoint which will receive traffic for all of the subdomains matching a given wildcard domain like *.example.com. You must create a wildcard domain to create a public wildcard endpoint.

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.
Loading…

Use multiple endpoints with wildcard subdomains​

With the Agent CLI, you can create separate public endpoints for subdomains of a wildcard domain no matter where the upstream services are running. See the Domains docs for more information.

For example, if you reserve *.example.com and want to route requests to api1.example.com and api2.example.com, you can specify subdomains via the CLI. ngrok will handle routing requests to the correct endpoint, even if they're on different ports.

The first one might be at port 80:

Loading…

While the second is at port 81:

Loading…
tip

This is only necessary for creating public endpoints to subdomains. Internal endpoints don't require a domain.

Randomly assigned hostnames​

If you run create a public endpoint without specifying a hostname, ngrok will automatically assign a random one for you.by selecting a random subdomain of one of our ngrok-managed Domains to your endpoint. For example, the command ngrok http 80 may create an endpoint like https://1eb2-181-80-12-3.ngrok.app.

The following example create an HTTPS endpoint on a randomly assigned hostname that forwards to port 8080.

Loading…

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​

Adds a username and password with the Basic Auth Traffic Policy action.

Loading…
traffic-policy.yml​
Loading…

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.

Loading…
traffic-policy.yml​
Loading…

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.

Loading…
traffic-policy.yml​
Loading…

Agent Forwarding​

The ngrok agent and Agent SDKs forward traffic that your endpoints receive to upstream services. You specify a URL or port number to instruct the ngrok agent where and how to forward traffic.

HTTPS forwarding​

The scheme in your upstream URL is used to determine whether to forward HTTP or HTTPS traffic to the upstream service. If you do not specify a scheme, the default http scheme is chosen unless you forward to port 443, in which case ngrok will use https. Consult the following table of examples.

Upstream URLNormalized Value
http://localhost:1234http://localhost:1234
https://localhost:1234https://localhost:1234
localhost:1234http://localhost:1234
1234http://localhost:1234
localhost:443https://localhost:443
443https://localhost:443

ngrok assumes that the network you run the agent on is private and it does not verify the TLS certificate presented by the upstream service. You may change this behavior with the flags --upstream-tls-verify and upstream-tls-verify-cas.

Loading…

Non-local forwarding​

Agents don't just forward to ports on your localhost. You can forward traffic to any address or URL reachable from the agent. For example, if you want to forward traffic to a HTTP server running on your network at 192.168.1.2:80:

Loading…

HTTP/2 forwarding​

When agents forward to upstream http/2 services, connections use HTTP/1.1 by default.

You can configure the agent, SDKs and Kubernetes Operator to instead use HTTP/2 when forwarding to your upstream service.

ForwarderOptionDocs
Agent--upstream-protocolAgent CLI flags
Agent SDKslanguage-dependentAgent SDKs
Kubernetes OperatorappProtocol on the Tunnel CRDKubernetes Operator

When http2 forwarding is enabled, all requests to your upstream service will be transmitted over HTTP/2 Cleartext since TLS was already terminated at the ngrok cloud service. We cannot use TLS-ALPN at this time. We rely on HTTP/2 with Prior Knowledge currently.

Serving file directories​

The ngrok agent supports the file:// scheme in a forwarding URL. When you use the file:// scheme, the ngrok agent serves local file system directories by using its own built-in file server, no separate server needed. It works just like python3 -m http.server but it is built directly into the ngrok agent.

Paths in file:// URLs must be specified as absolute paths.

Serve files in /var/log​

Loading…

Serve files on Windows​

Loading…

Serve files in your current working directory​

Loading…

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

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

EventWhen
http_request_complete.v0Published when an HTTP request to an HTTP/S endpoints completes.
tcp_connection_closed.v0Published 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.

The section on HTTP/2 agent forwarding has details on how to configure the use of HTTP/2 when sending traffic to an upstream service.

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 to the upstream service. As an exception, Connection: upgrade headers are forwarded 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 (aka 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 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 setup, 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 agent or in your upstream application, use a TLS Endpoint instead.

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

Upstream Headers​

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

HeaderDescription
x-forwarded-forThe 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-protoThe 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-hostThe 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 us if you need to configure limits and timeouts on connections to HTTP endpoints.

Connection​

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

LimitNameNotes
60 secondsTLS Handshake DurationTime between ClientHello received and handshake completion
64 KBHandshake Message SizeMax size of non-certificate handshake messages
256 KBCertificate Message SizeMax size of certificate handshake messages
16 KBRecord Payload Size

HTTP​

LimitNameNotes
No timeoutRound Trip TimeoutTime for the entire HTTP request and response

HTTP Request​

LimitNameNotes
1 MBRequest Header SizeIncludes method, URI and headers
1 MBRequest URI LengthLimited by the size of the request header
No timeoutRequest TimeoutTime to read the entire HTTP request from the client
No timeoutRequest Header TimeoutTime to read the HTTP request header from the client
No limitRequest Body Size

HTTP Response​

LimitNameNotes
1 MBResponse Header SizeIncludes method, URI and headers
No timeoutResponse TimeoutTime to read the entire HTTP response from the server
No timeoutResponse Header TimeoutTime to read the HTTP response header from the server
No limitResponse 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 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 action rejected the request.
  • Traffic Policy execution encountered a runtime error.
  • ngrok encountered an internal error

API​

HTTP/S Endpoints can be created programatically. Consult the documentation on Endpoint APIs.

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 domains and more.