ngrok

▾ Index
Don't have an ngrok account?

Sign up for free to get more bandwidth, longer tunnel timeouts, and a lot more.

ngrok Link Documentation

ngrok link is a specialized, enhanced version of ngrok specifically designed for running in production environments. Specifically, it is intended for two major use cases:

  1. It is a lightweight VPN alternative that provides the automation and security necessary to establish targeted, secure links into customer environments.
  2. It enables IoT devices to expose control functionality to customers or administrators at stable, secured endpoints. Remote shell access for debugging and administration can be safely exposed in this manner as well.

ngrok link is tuned for running optimally as part of your infrastructure and exposes a number of additional security features to give fine grained access and authentication control. Most importantly, these features are exposed via APIs so that you can automate your entire workflow with ngrok.

Intended Audience

THIS DOCUMENT ASSUMES YOU HAVE ALREADY READ AND UNDERSTOOD the ngrok documentation. If you have not, you should read the main documentation now. The following content is intended only as a supplement and will not be helpful without the proper context.

Differences

Because ngrok link is specialized for production environments, there are changes in the way it operates compared to a 'standard' ngrok agent. Those differences are enumerated here.

The following changes have been made to ngrok's configuration defaults.

Installing ngrok as a service

ngrok link includes additional functionality that makes it easy to install and manage itself as a native operating system service on Windows, OS X and Linux. This makes it extraordinarily easy to set up ngrok in a production configuration that will cause it to start on machine boot, restart after crashes, and integrate with the native tools system administrators are familiar with to manage and inspect its state.

When running as a service, ngrok configures itself from its configuration file and starts all tunnels defined in the configuration file. When ngrok runs as a service, it executes the equivalent behavior of running ngrok start --all.

Installation

Installing ngrok as a service is the same on all on operating systems. First, create an ngrok.yml configuration file somewhere on your machine. For this example, I'll assume it's in C:\ngrok\ngrok.yml. In your configuration file, make sure you include an authtoken and define all of the tunnels that you want to start. Then run:

ngrok service install -config C:\ngrok\ngrok.yml

This will validate that the configuration file is valid, and if so, install ngrok as a service using the given configuration file. The service installation includes the location of the ngrok binary, so don't move or delete it after you've installed the service.

Management

After your service is installed, you probably want to start it. You can easily do that with:

ngrok service start

ngrok exposes the following commands to make service administration easy. The commands take no arguments and do what you would expect.

Windows

On Windows, ngrok installs itself as a Windows service. It can be managed via Windows Services and it logs all errors and warnings to the Windows event log.

OS X

On Darwin, ngrok creates an appropriate plist file and installs itself to run via launchd. Warnings and errors are logged via syslog.

Linux

On Linux, only systems with upstart or systemd installed are supported for service installation. If neither is installed, you will need to set up your own management of the ngrok process as a service. Warnings and errors are logged via syslog.

Per-client Authtoken Credentials

For production systems, every client must authenticate with a unique authtoken credential. This allows you to deactivate devices that are old or compromised. Further, it allows you to enforce a separate ACL policy on every connected device that limits what tunnels it is allowed to bind.

Generation

You can create authtokens from the Auth tab in your ngrok dashboard and click the Auth tab. Under the section "Tunnel Authtokens", click "New Credential". You may optionally enter a human-readable description of the device or location where you intend to install the authtoken for tracking purposes.

In both the UI and API, the full authtoken you generate will only be shown once, immediately after creation!

ACL Enforcement

Credential ACLs describe what a client who connects with a given authtoken is allowed to do. For example, you may want to restrict each client to only have permission to bind a specific set of tunnel endpoints. When you create a credential, specify a list of ACL behaviors are allowed for any client connecting with that authtoken.

Generating credentials with ACLs is only available via the create credential API at the moment.

Endpoint Configurations

Endpoint configurations define reusable pieces of functionality that can be applied to any number of reserved domains or reserved addresses on your account.

Endpoint configurations are comprised of one or more modules. Each module defines a piece of functionality that will be executed on traffic that transits through any domain or address that you attach the endpoint configuration to. Each module defines its own set of configuration options and may be managed independently via its own API resources. Modules can perform authentication, performance optimizations like compression, enrich requests, handle errors, enforce policy and more.

Endpoint Configuration Types

Every endpoint configuration must be defined with a type. The type determines both which modules may be added to the configuration as well as how the configuration may be attached to a reserved domain or reserved address. The documentation for each module will list the configuration types it may be added to.

There are currently three types of endpoint configurations: http, https, and tcp.

Attaching to Reserved Domains and Addresses

Endpoint configurations may be attached to any number of reserved domains or addresses. When the configuration is attached, that domain or address will start applying the configuration's modules to traffic that transits through any tunnels started on those domains or addresses.

Reserved domains have two endpoint configuration references: http_endpoint_configuration_id and https_endpoint_configuration_id. These govern how http and https traffic are handled, respectively. The type of configuration that you attach must be http and https, respectively, for those references.

Reserved addresses have a single endpoint configuration reference endpoint_configuration_id. This configuration reference must be of type tcp.

Changes to HTTP Traffic

Traffic that is handled by endpoint configurations goes through a new codepath in ngrok's edge servers. This new codepath has a few subtle changes to how HTTP traffic is handled that are enumerated below:

Header Casing

HTTP headers the backend sees now have their capitalization canonicalized. The HTTP RFC defines this change as compatible. Previously,

curl --header “foo-BAR: baz” foo.ngrok.io
resulted in the backend seeing
foo-BAR: baz
now it sees:
Foo-Bar: baz

Header Ordering

HTTP headers now may be reordered whereas ngrok previously never re-ordered headers. The HTTP RFC defines this behavior as compatible.

X-Forwarded-For

If an X-Forwarded-For header was supplied by the caller, ngrok now combines those values in a single header field. The RFC describing X-Forwarded-For describes this as the intended behavior. Previously,

curl --header “X-Forwarded-For: 1.2.3.4” foo.ngrok.io
resulted in the backend seeing:
X-Forwarded-For: 1.2.3.4
X-Forwarded-For: 5.6.7.8
Now it sees:
X-Forwarded-For: 1.2.3.4, 5.6.7.8

Stripped Hop-By-Hop Headers

ngrok used to pass through the following hop-by-hop headers. It will now strip them (and set its own values, if necessary).

Endpoint Configuration Modules

Basic Auth

Supported on types: ,

The Basic Auth module allows you to enforce username/password authentication on all incoming requests to the endpoint via HTTP Basic Authentication. If the supplied credentials are invalid, ngrok will respond with a 401 Unauthorized response.

ngrok support pluggable authentication providers to validate the supplied credentials. Currently, the only supported provider is agent which instructs ngrok to validate using the credentials passed from the ngrok agent that initiated the tunnel via its -auth command line parameter or auth configuration file value.

Circuit Breaker

Supported on types: ,

Circuit breakers are used to protect upstream servers by rejecting traffic to them when they become overwhelmed, allowing them time to recover back into a steady operational state. When the upstream server starts to fail requests at too high of a rate, the circuit is "opened".

The circuit breaker is an implementation of Netflix's Hystrix circuit breaker specification.

If the upstream server responds with more than the threshold percentage of requests with 50X status codes, the circuit breaker pre-emptively reject all subsequent requests at the ngrok edge with a 503 until the upstream server's error rate drops below the threshold percentage.

Compression

Supported on types: ,

The Compression middleware automatically compresses your responses between the http client and the ngrok edge which can make your websites load faster on low bandwidth networks.

If an HTTP request includes an Accept-Encoding header, HTTP responses will be automatically compressed and a Content-Encoding response header will be added.

If the response was already compressed by the upstream server, ngrok takes no action.

gzip and deflate encodings are supported.

HTTPS

Supported on type:

The HTTPS module allows you to configure whether ngrok terminates TLS traffic at its edge or forwards the TLS traffic through unterminated, in which case the TLS traffic will need to be terminated by your application server (or by the ngrok agent).

If an HTTPS module is not specified, the default behavior is to terminate all TLS traffic at the ngrok edge.

If the HTTPS module is enabled and TLS termination has been disabled, then you must have the ngrok agent start a tls tunnel to receive traffic. Furthermore, if TLS termination is disabled, no other http or https modules (e.g. Compression, Basic Auth, etc) will be supported on this endpoint configuration.

If you update a configuration to change whether it terminates TLS traffic or not, all tunnels running with that configuration will immediately begin to fail requests. All tunnels started with that configuration will need to be stopped and then restarted with their protocol changed (either https -> tls or vice-versa.

IP Policy

Supported on types: , ,

The IP Policy modules lets you restrict the allowed traffic to tunnel endpoints by explicitly whitelisting a set of IPs that are permitted to access those endpoints.

Allow connections to the tunnel endpoint only if the source IP of the connection matches an IP or IP range in any of the specified IP Policies. If multiple policies are specified, a connection will be allowed if it matches an IP address in any of the policies. Formally, the IP is checked against a union of all the IP policies.

The IP policy module is intended to replace and deprecate the existing IP Whitelist resource. Please read the documentation section about IP policy and IP whitelist interactions carefully.

Mutual TLS Authentication

Supported on type:

Also known as "TLS client authentication", connections must complete a mutual TLS handshake in which the client presents a valid certificate signed by any of the root certificate authorities that you upload.

The Common Name of the client's TLS certificate is injected into the header X-Tls-Client-Cn that is sent to your application server. This allows you to identify the requesting client for purposes of group membership, permissioning, revocation checks, profile lookup, etc.

Root CAs must be specified in PEM format. You may specify multiple root CAs by concatenating them together.

Request Headers

Supported on types: ,

The Request Headers module allows you to specify a set of key/value pairs that will be injected as headers into the HTTP request before it is sent to your upstream server.

If a specified header key already exists in an HTTP request, the header will appear multiple times; the original header value will not be overwritten.

Webhook Validation

Supported on types: ,

The webhook validation module allows ngrok to assert requests to your endoint originate from a supported webhook provider like Slack or Github.

If ngrok can't validate a request as coming from the configured provider it will reject the request with a 403 status.

IP Policies

IP policies are a reusable group of whitelisted IPs or IP ranges (in CIDR blocks) that can be applied on a per-tunnel basis via Endpoint Configurations. An endpoint configuration may specify one or more IP policies. IP policies may be attached to any number of endpoint configurations. If an endpoint configuration specifies multiple IP policies, a connection will be allowed if its source IP matches any policy. Formally, the endpoint configuration defines a computed union of all of its IP policies.

IP Policy Rules

Every IP policy consists of zero or more IP policy rules. Each rule specifies an IP address or IP address range in CIDR notation. Both IPv4 and IPv6 address notations are supported. An IP policy with no rules is valid and will match no IPs.

Interaction with IP Whitelist

IP policies are intended to replace and deprecate the previous primitive ngrok used for IP enforcement, the IP whitelist. Unlike IP policies which must be explicitly associated with tunnels via an endpoint configuration, The IP whitelist is an account-wide primitive that applies to all tunnels on your account.

We do not recommend using both IP policies and the IP whitelist together. But, if you do, a connection will only be allowed through if it matches both the IP whitelist and the configured IP policies. Formally, for a connection to be accepted, it must match the intersection of both the IP whitelist and IP policies configured for the matching endpoint configuration.

The ngrok.com REST API

ngrok.com exposes a REST API that grants programmatic access to all of ngrok's resources.

Base URL and Authentication

Base URL https://api.ngrok.com/
Authentication Bearer token authentication with an ngrok.com API key token

The API keys to access the ngrok.com REST API are available on your ngrok.com dashboard under the Auth tab. API keys can also be created via the API keys API. All requests to the API must include an API key as a bearer token in the Authorization header as demonstrated in the following example.

Access the root API resource
curl -H "Authorization: Bearer <<TOKEN>>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/

Supported Content Types

Request parameters may be encoded to the API using either application/x-www-form-urlencoded or application/json. Ensure that your client sets the request's Content-Type header appropriately. All responses returned by the API are application/json.

Versioning and API Stability

The caller must specify a version by sending an X-Ngrok-Version header with each request. The latest version is 1. Version 0 is supported but deprecated.

The ngrok.com API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. Examples of non-breaking changes to the API that will not be opt-in include the following.

List Tunnels

Returns a list of all tunnels online for your account

Request
GET/tunnels
Response
Parameters
tunnels list of all online tunnels for this account
Tunnel Object Parameters
id unique tunnel resource identifier
clients list of all clients hosting the tunnel. This list will always have at least one entry. Deprecated after Version 0
proto tunnel protocol type
region identifier of region where tunnel is hosted
public_url URL of the tunnel's public endpoint
metadata

user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option

In API version 0, this value was instead pulled from the top-level metadata configuration option.

started_at ISO-8601 timestamp of when the tunnel was initiated
tunnel_session the tunnel session this tunnel was started on since Version 1
Client Object Parameters
id UUID of the ngrok agent. It is generated each time an ngrok agent starts
ip IP address of client hosting the tunnel
version version of the ngrok agent
Tunnel Session Object Parameters
id Unique resource identifier of the tunnel session
uri URI to API resource of the tunnel session
Example Response
{
  "tunnels": [
      {
          "tunnel_session": {
              "id": "ts_1OfdQQ2mLyo7c94seZKLjAtOuBT",
              "uri": "https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT"
          },
          "proto": "http",
          "id": "tn_4d64bf1c28140377fe7538bf6ffd8238",
          "public_url": "http://095f807b.ngrok.io",
          "region": "us",
          "metadata": "",
          "started_at": "2015-01-21T02:39:29Z"
      },
      {
          "tunnel_session": {
              "id": "ts_1OfdQQ2mLyo7c94seZKLjAtOuBT",
              "uri": "https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT"
          },
          "proto": "https",
          "public_url": "https://095f807b.ngrok.io",
          "region": "us",
          "metadata": "",
          "id": "tn_928949b3ae2783a804d9b7bba1dfdb35",
          "started_at": "2015-01-21T02:39:29Z"
      }
  ],
  "uri": "https://api.ngrok.com/tunnels"
}

List Tunnel Sessions

Returns a list of all online tunnel sessions for your account

Request
GET/tunnel_sessions
Response
Parameters
tunnel_sessions list of all online tunnel sessions for this account
agent_version version of the ngrok agent that started this ngrok tunnel session
credential the credential or ssh credential used by the ngrok agent to start this tunnel session
id unique tunnel session resource identifier
ip source ip address of the tunnel session
metadata arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option
os operating system of the host the ngrok agent is running on
region the ngrok region identifier in which this tunnel session was started
started_at time when the tunnel session first connected to the ngrok servers
transport the transport protocol used to start the tunnel session. One of ngrok/v2 or ssh
uri URI to the API resource of the tunnel session
Credential Object Parameters
id unique identifier of the credential (or ssh credential)
uri URI to the API resource of the credential (or ssh credential)
Example Response
{
  "tunnel_sessions": [
    {
      "client_version": "2.3.34",
      "credential": {
        "id": "cr_1O4GEf0pfEqmofQQwVXsy1ma8XY",
        "uri": "https://api.ngrok.com/credentials/cr_1O4GEf0pfEqmofQQwVXsy1ma8XY"
      },
      "id": "ts_1OfdQQ2mLyo7c94seZKLjAtOuBT",
      "ip": "10.11.1.5",
      "metadata": "location A",
      "os": "linux",
      "region": "us",
      "started_at": "2019-07-29T03:56:07Z",
      "transport": "ngrok/v2",
      "uri": "https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT"
    }
  ],
  "uri": "https://api.ngrok.com/tunnel_sessions"
}

Stop Tunnel Session Agent

Issues a command instructing the ngrok agent that started this tunnel session to exit.

Request
POST/tunnel_sessions/:id/stop
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -X POST https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT/stop
Response

Returns a 204 with no body on success.

Restart Tunnel Session Agent

Issues a command instructing the ngrok agent to restart. The agent restarts itself by calling exec() on platforms that support it. This operation is notably not supported on Windows.

When an agent restarts, it reconnects with a new tunnel session ID.

Request
POST/tunnel_sessions/:id/stop
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -X POST https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT/restart
Response

Returns a 204 with no body on success.

Update Tunnel Session Agent

Issues a command instructing the ngrok agent to update itself to the latest version. After this call completes successfully, the ngrok agent will be in the update process. A caller should wait some amount of time to allow the update to complete (at least 10 seconds) before making a call to the Restart endpoint to request that the agent restart itself to start using the new code.

This call will never update an ngrok agent to a new major version which could cause breaking compatibility issues. If you wish to update to a new major version, that must be done manually. Still, please be aware that updating your ngrok agent could break your integration.

This call will fail in any of the following circumstances:

  • there is no update available
  • the ngrok agent's configuration disabled update checks
  • the agent is currently in process of updating
  • the agent has already successfully updated but has not yet been restarted

Request
POST/tunnel_sessions/:id/stop
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -X POST https://api.ngrok.com/tunnel_sessions/ts_1OfdQQ2mLyo7c94seZKLjAtOuBT/update
Response

Returns a 204 with no body on success.

List Reserved Domains

Returns a list of all domains reserved for your account

Request
GET/reserved_domains
Response
Parameters
reserved_domains the list of reserved domains for this account
Reserved Domain Object Parameters
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
created_at time of domain reservation as an ISO-8601 timestamp
description human-readable description of this reserved domain.
domain name of the reserved domain
http_endpoint_configuration object reference to the endpoint configuration that defines how http traffic to this domain is handled or null, if not present
https_endpoint_configuration object reference to the endpoint configuration that defines how https traffic to this domain is handled or null, if not present
id unique reserved domain resource identifier
metadata arbitrary user-defined data of this reserved domain.
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved domain
Example Response
{
  "reserved_domains": [
      {
          "cname_target": null,
          "created_at": "2014-03-02T09:28:35Z",
          "description": "",
          "domain": "demo-server.ngrok.io",
          "http_endpoint_configuration": null,
          "https_endpoint_configuration": {
            "id": "ec_1Oe8Eq50unsqn4RJCsHYOgpClVv",
            "uri": "https://api.ngrok.com/endpoint_configurations/ec_1Oe8Eq50unsqn4RJCsHYOgpClVv",
          },
          "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
          "metadata": "",
          "region": "us",
          "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
      },
      {
          "cname_target": "m2qgkjdu.cname.us.ngrok.io",
          "created_at": "2014-05-30T17:10:49Z",
          "description": "Device 0001 Dashboard",
          "domain": "manage-0001.app.example.com",
          "http_endpoint_configuration": null,
          "https_endpoint_configuration": null,
          "id": "rd_82hVw9caM9qHAwAreLhY9",
          "metadata": "{\"service\": \"dashboard\"}",
          "region": "us",
          "uri": "https://api.ngrok.com/reserved_domains/rd_82hVw9caM9qHAwAreLhY9"
      }
  ],
  "uri": "https://api.ngrok.com/reserved_domains"
}

Reserve Domain

Reserves a new domain for your account

Request
POST/reserved_domains
Parameters
description human-readable description of this reserved domain. Optional, max 255 bytes.
name the domain name to reserve. It may be a full domain name like app.example.com. If the name does not contain a '.' it will reserve that subdomain on ngrok.io.
http_endpoint_configuration_id ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
https_endpoint_configuration_id ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
metadata arbitrary user-defined data of this reserved domain. Optional, max 4096 bytes.
region reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us)
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d "name=app&region=au" https://api.ngrok.com/reserved_domains
Response

Returns a 201 status code on successful reservation of the domain

Parameters
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
created_at time of domain reservation as an ISO-8601 timestamp
description human-readable description of this reserved domain.
domain name of the reserved domain
http_endpoint_configuration object reference to the endpoint configuration that defines how http traffic to this domain is handled or null, if not present
https_endpoint_configuration object reference to the endpoint configuration that defines how https traffic to this domain is handled or null, if not present
id unique reserved domain resource identifier
metadata arbitrary user-defined data of this reserved domain.
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved domain
Example Response
{
  "cname_target": null,
  "created_at": "2015-01-02T09:28:35Z",
  "description: "",
  "domain": "app.au.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
  "metadata": "",
  "region": "au",
  "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
}

Reserved Domain Detail

Returns detailed information about a reserved domain.

Request
GET/reserved_domains/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response
Parameters
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
created_at time of domain reservation as an ISO-8601 timestamp
description human-readable description of this reserved domain.
domain name of the reserved domain
http_endpoint_configuration object reference to the endpoint configuration that defines how http traffic to this domain is handled or null, if not present
https_endpoint_configuration object reference to the endpoint configuration that defines how https traffic to this domain is handled or null, if not present
id unique reserved domain resource identifier
metadata arbitrary user-defined data of this reserved domain.
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved domain
Example Response
{
  "cname_target": null,
  "created_at": "2015-01-02T09:28:35Z",
  "description": "",
  "domain": "app.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
  "metadata": "",
  "region": "us",
  "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
}

Update Reserved Domain

Update attributes of a reserved domain record

Request
PATCH/reserved_domains/:id
Example Request
Parameters
description human-readable description of this reserved domain. Optional, max 255 bytes.
http_endpoint_configuration_id ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
https_endpoint_configuration_id ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
metadata arbitrary user-defined data of this reserved domain. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'https_endpoint_configuration_id=ec_1OfqEc1rFVb9JZAaV4hOQ6x8ko&description=kiosk-0004&metadata={"uuid": "be281fe2-327c-4651-aea7-bc664493681d", "service": "api"}' https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response

Returns a 200 status code on successful update of the reserved domain record

Parameters
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
created_at time of domain reservation as an ISO-8601 timestamp
description human-readable description of this reserved domain.
domain name of the reserved domain
http_endpoint_configuration object reference to the endpoint configuration that defines how http traffic to this domain is handled or null, if not present
https_endpoint_configuration object reference to the endpoint configuration that defines how https traffic to this domain is handled or null, if not present
id unique reserved domain resource identifier
metadata arbitrary user-defined data of this reserved domain.
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved domain
Example Response
{
  "cname_target": null,
  "created_at": "2015-01-02T09:28:35Z",
  "description": "kiosk-0004",
  "domain": "app.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": {
      "id": "ec_1OfqEc1rFVb9JZAaV4hOQ6x8ko",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OfqEc1rFVb9JZAaV4hOQ6x8ko"
  },
  "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
  "metadata": "{\"uuid\": \"be281fe2-327c-4651-aea7-bc664493681d\", \"service\": \"api\"}",
  "region": "us",
  "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
}

Release Reserved Domain

Release a reserved domain

Request
DELETE/reserved_domains/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response

Returns a 204 response with no body on success

List Reserved Addresses

Returns a list of all TCP addresses reserved for your account

Request
GET/reserved_addrs
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/reserved_addrs
Response
Parameters
reserved_addrs the list of reserved addresses for this account
Reserved Addr Object Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
description human-readable description of this reserved address.
endpoint_configuration reference to the endpoint configuration that defines how traffic to this address is handled or null, if not present
id unique reserved address resource identifier
metadata arbitrary user-defined data of this reserved address.
region identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved address
Example Response
{
  "reserved_addrs": [
      {
          "addr": "1.tcp.au.ngrok.io:20003",
          "created_at": "2015-01-02T13:49:21Z",
          "description": "SSH for device A001",
          "endpoint_configuration": null,
          "id": "ra_2ABmiPTLgavPn8PYYNMS3",
          "metadata": "",
          "region": "au",
          "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
      },
      {
          "addr": "1.tcp.eu.ngrok.io:20001",
          "created_at": "2015-01-02T13:49:21Z",
          "description": "SSH for device A002",
          "endpoint_configuration": {
              "id": "ec_1OfqEcH5wQ1urhU2PgOwr3IKMSp",
              "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OfqEcH5wQ1urhU2PgOwr3IKMSp"
          },
          "id": "ra_5mhjYkKVE1LpVW5G3UaAz",
          "metadata": "",
          "region": "eu",
          "uri": "https://api.ngrok.com/reserved_addrs/ra_5mhjYkKVE1LpVW5G3UaAZ"
      }
  ],
  "uri": "https://api.ngrok.com/reserved_addrs"
}

Reserve Address

Reserve a new address for your account

Request
POST/reserved_addrs
Example Request
Parameters
region reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us)
description human-readable description of this reserved address. Optional, max 255 bytes.
endpoint_configuration_id id of the endpoint configuration that defines how to handle traffic to this address
metadata arbitrary user-defined data of this reserved address. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d "region=us" https://api.ngrok.com/reserved_addrs
Response

Returns a 201 status code on successful reservation of an address

Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
description human-readable description of this reserved address.
endpoint_configuration reference to the endpoint configuration that defines how traffic to this address is handled or null, if not present
id unique reserved address resource identifier
metadata arbitrary user-defined data of this reserved address.
region identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved address
Example Response
{
  "addr": "1.tcp.ngrok.io:20003",
  "created_at": "2015-01-02T13:49:21Z",
  "description: "",
  "endpoint_configuration": null,
  "id": "ra_2ABmiPTLgavPn8PYYNMS3",
  "metadata": "",
  "region": "us",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
}

Reserved Address Detail

Returns detailed information about a reserved address.

Request
GET/reserved_addrs/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS3
Response
Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
description human-readable description of this reserved address.
endpoint_configuration reference to the endpoint configuration that defines how traffic to this address is handled or null, if not present
id unique reserved address resource identifier
metadata arbitrary user-defined data of this reserved address.
region identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved address
Example Response
{
  "addr": "1.tcp.ngrok.io:20003",
  "created_at": "2015-01-02T13:49:21Z",
  "description: "",
  "endpoint_configuration": null,
  "id": "ra_2ABmiPTLgavPn8PYYNMS3",
  "metadata": "",
  "region": "us",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
}

Update Reserved Address

Update attributes of a reserved address record

Request
PATCH/reserved_addrs/:id
Example Request
Parameters
description human-readable description of this reserved address. Optional, max 255 bytes.
endpoint_configuration_id id the endpoint configuration that defines how handle traffic to this address, or null to remove it
metadata arbitrary user-defined data of this reserved address. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'description=control agent (device red-12)&metadata={"uuid": "b8cc2b5f-e924-4fcb-b2e9-626ee111f405&endpoint_configuration_id=ec_1OfqEcH5wQ1urhU2PgOwr3IKMSp", "service": "agent"}' https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS3
Response

Returns a 200 status code on successful update of the reserved address record

Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
description human-readable description of this reserved address.
endpoint_configuration reference to the endpoint configuration that defines how traffic to this address is handled or null, if not present
id unique reserved address resource identifier
metadata arbitrary user-defined data of this reserved address.
region identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to the API resource of the reserved address
Example Response
{
  "addr": "1.tcp.ngrok.io:20003",
  "created_at": "2015-01-02T13:49:21Z",
  "description": "control agent (device red-12)",
  "endpoint_configuration": {
      "id": "ec_1OfqEcH5wQ1urhU2PgOwr3IKMSp",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OfqEcH5wQ1urhU2PgOwr3IKMSp"
  },
  "id": "ra_2ABmiPTLgavPn8PYYNMS3",
  "metadata": "{\"uuid\": \"b8cc2b5f-e924-4fcb-b2e9-626ee111f405\", \"service\": \"agent\"}",
  "region": "us",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
}

Release Reserved Address

Release a reserved address

Request
DELETE/reserved_addrs/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS3
Response

Returns a 204 response with no body on success

List API Keys

Returns a list of all API keys for your account

Request
GET/api_keys
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/api_keys
Response
Parameters
keys the list of api keys for this account
API key object parameters
token the bearer token used to authenticate requests to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
description optional description of who or what uses the key to authenticate
created_at time of key creation
id unique key resource identifier
metadata arbitrary user-defined data of this key
uri URI to the API resource of the key
Example Response
{
    "keys": [
        {
            "created_at": "2019-10-04T17:53:10Z",
            "description": "Bootstrap token",
            "id": "ak_1RkWUPh7XwG9xX9feThgJ18ExMG",
            "metadata": "{\"environment\":\"dev\"}",
            "token": null,
            "uri": "https://api.ngrok.com/api_keys/ak_1RkWUPh7XwG9xX9feThgJ18ExMG"
        },
        {
            "created_at": "2019-10-04T19:36:26Z",
            "description": "API generated token",
            "id": "ak_1Rkj3FMQURdt1wJCf30cOnXDeGi",
            "metadata": "{\"environment\":\"prod-us\"}",
            "token": null,
            "uri": "https://api.ngrok.com/api_keys/ak_1Rkj3FMQURdt1wJCf30cOnXDeGi"
        }
    ],
    "uri": "https://api.ngrok.com/api_keys"
}

Create API Key

Generate a new API key.

Request
POST/api_keys
Example Request
Parameters
description human-readable description of this API key. Optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>"\
  -H "X-Ngrok-Version: 1"\
  -H "Content-Type: application/json"\
  -X POST \
  -d '{"description":"my api key", "metadata":"{\"environment\":\"dev\"}"}'\
  https://api.ngrok.com/api_keys
Response

Returns a 201 status code on successful creation of an API key

Parameters
token the bearer token used to authenticate requests to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
description optional description of who or what uses the key to authenticate
created_at time of key creation
id unique key resource identifier
metadata arbitrary user-defined data of this key
uri URI to the API resource of the key
Example Response
{
    "created_at": "2019-10-04T21:25:47Z",
    "description": "my api key",
    "id": "ak_1RkwLl07Le040oVolPlDtRhXZdT",
    "metadata": "{\"environment\":\"dev\"}",
    "token": "1RkwLl07Le040oVolPlDtRhXZdT_6obGLiXt7sVaRmTy3mSHP",
    "uri": "https://api.ngrok.com/api_keys/ak_1RkwLl070oVolPlDtRhXZdT"
}

API Key Detail

Returns detailed information about an API key

Request
GET/api_keys/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/api_keys/ak_85PtDp9AjRaESHPatReaNx
Response
Parameters
token the bearer token used to authenticate requests to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
description optional description of who or what uses the key to authenticate
created_at time of key creation
id unique key resource identifier
metadata arbitrary user-defined data of this key
uri URI to the API resource of the key
Example Response
{
    "created_at": "2019-10-04T19:36:26Z",
    "description": "API generated token",
    "id": "ak_1Rkj3FMQURdt1wJCf30cOnXDeGi",
    "metadata": "{\"environment\":\"dev\"}",
    "token": null,
    "uri": "https://api.ngrok.com/api_keys/ak_1Rkj3FMQURdt1wJCf30cOnXDeGi"
}

Update API Key

Update attributes of an API key

Request
PATCH/api_key/:id
Example Request
Parameters
description human-readable description of this API key. Optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>"\
    -H "X-Ngrok-Version: 1"\
    -H "Content-Type: application/json"\
    -X PATCH \
    -d '{"description":"changed", "metadata":"{}"}'\
    https://api.ngrok.com/api_keys/ak_1RkibPGOvBv1l5AHkDS14iIxKN6 
Response

Returns a 200 status code on successful update of the API key

Parameters
token the bearer token used to authenticate requests to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
description optional description of who or what uses the key to authenticate
created_at time of key creation
id unique key resource identifier
metadata arbitrary user-defined data of this key
uri URI to the API resource of the key
Example Response
{
    "created_at": "2019-10-04T19:32:46Z",
    "description": "changed",
    "id": "ak_1RkibPGOvBv1l5AHkDS14iIxKN6",
    "metadata": "{}",
    "token": null,
    "uri": "https://api.ngrok.com/api_keys/ak_1RkibPGOvBv1l5AHkDS14iIxKN6"
}

Delete API Key

Delete an API Key

Request
DELETE/api_keys/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>"\
    -H "X-Ngrok-Version: 1"\
    -H "Content-Type: application/json"\
    -X DELETE \
    https://api.ngrok.com/api_keys/ak_1RkjX6tGS77uTr2QMlubnjRbzk6
Response

Returns a 204 response with no body on success

List Tunnel Credentials

Returns a list of all tunnel credentials for your account

Request
GET/credentials
Response
Parameters
credentials the list of tunnel credentials for this account
Credential Object Parameters
token the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation. Otherwise it is null.
description optional description of who or what uses the credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this credential's authtoken is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of credential creation
id unique credential resource identifier
metadata arbitrary user-defined data of this credential
uri URI to the API resource of the credential
Example Response
{
  "credentials": [
      {
          "acl": [
              "bind:1.tcp.ngrok.io.dev:20001",
              "bind:129.devices.company.com"
          ],
          "created_at": "2015-02-06T22:45:14Z",
          "description": "for device #129",
          "id": "cr_5bXkieNwPF5eRvu6ym958",
          "metadata": "",
          "token": null,
          "uri": "https://api.ngrok.com/credentials/cr_5bXkieNwPF5eRvu6ym958"
      },
      {
          "acl": [
              "bind:1.tcp.ngrok.io.dev:20002",
              "bind:132.devices.company.com"
          ],
          "created_at": "2015-03-01T17:35:58Z",
          "description": "for device #132",
          "id": "cr_2HxDq3BuKpyEMeesbuLq8",
          "metadata": "",
          "token": null,
          "uri": "https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8"
      }
  ],
  "uri": "https://api.ngrok.com/credentials"
}

Create Tunnel Credential

Create a new tunnel authtoken credential for your account. The response to this API call is the only time the generated token is available. If you need it for future use, you must save it securely yourself.

Request
POST/credentials
Parameters
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
acl a list of ACL rules. Optional. If unspecified, the credential will have all permissions. The only allowed ACL rule at this time is the bind rule. The bind rule allows you to restrict what domains and addresses the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:*.example.com which will allow x.example.com, y.example.com, *.example.com, etc.
metadata arbitrary user-defined data of this credential. Optional, max 4096 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"description":"for device #132", "acl": ["bind:myname.com", "bind:1.tcp.ngrok.io:20001"]}' https://api.ngrok.com/credentials
Response

Returns a 201 status code on successful creation of the credential

Parameters
token the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation. Otherwise it is null.
description optional description of who or what uses the credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this credential's authtoken is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of credential creation
id unique credential resource identifier
metadata arbitrary user-defined data of this credential
uri URI to the API resource of the credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "cr_2HxDq3BuKpyEMeesbuLq8",
  "metadata": "",
  "token": "2HxDq3BuKpyEMeesbuLq8_6M1tTg7DyfkVsKUyq9K65",
  "uri": "https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8"
}

Tunnel Credential Detail

Returns detailed information about a tunnel authtoken credential

Request
GET/credentials/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8
Response
Parameters
token the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation. Otherwise it is null.
description optional description of who or what uses the credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this credential's authtoken is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of credential creation
id unique credential resource identifier
metadata arbitrary user-defined data of this credential
uri URI to the API resource of the credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "cr_2HxDq3BuKpyEMeesbuLq8",
  "metadata": "",
  "token": null,
  "uri": "https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8"
}

Update Tunnel Credential

Updates attributes of a tunnel authtoken credential record

Request
PATCH/credentials/:id
Parameters
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
acl a list of ACL rules. Optional. If unspecified, the credential will have all permissions. The only allowed ACL rule at this time is the bind rule. The bind rule allows you to restrict what domains and addresses the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io.
metadata arbitrary user-defined data of this credential. Optional, max 255 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'metadata={"device-id": "03424d6b-0ffa-4eb7-96aa-60aabfad20ba"}' https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8
Response
Parameters
token the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation. Otherwise it is null.
description optional description of who or what uses the credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this credential's authtoken is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of credential creation
id unique credential resource identifier
metadata arbitrary user-defined data of this credential
uri URI to the API resource of the credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "cr_2HxDq3BuKpyEMeesbuLq8",
  "metadata": "{\"device-id\": \"03424d6b-0ffa-4eb7-96aa-60aabfad20ba\"}",
  "token": null,
  "uri": "https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8"
}

Revoke Tunnel Credential

Revoke a credential so that it may no longer be used

Request
DELETE/credentials/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8
Response

Returns a 204 response with no body on success

List Endpoint Configurations

Returns a list of all endpoint configurations for your account

Request
GET/endpoint_configurations
Response
Parameters
endpoint_configurations the list of endpoint configurations for this account
Endpoint Configuration Object Parameters
type defines the type of traffic this configuration will handle, one of http, https, or tls
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
webhook_validation object with Webhook Validation module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
created_at time of endpoint configuration creation
id unique endpoint configuration resource identifier
metadata arbitrary user-defined data of this endpoint configuration
uri URI to the API resource of the endpoint configuration
Example Response
{
  "endpoint_configurations": [
    {
      "id": "ec_1OiIPuxZMEpBJUYZlIWF37xylMg",
      "type": "https",
      "description": "",
      "metadata": "",
      "created_at": "2019-07-30T02:32:49Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OiIPuxZMEpBJUYZlIWF37xylMg",
      "basic_auth": null,
      "circuit_breaker": null,
      "compression": {
        "enabled": true
      },
      "request_headers": null,
      "ip_policy": null,
      "mutual_tls": {
        "enabled": true,
        "client_cas": "-----BEGIN CERTIFICATE-----\nMIID3TCCAsWgAwIBAgIJAKUYg8G7gMYIMA0GCSqGSIb3DQEBBQUAMFIxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRIwEAYDVQQKEwluZ3Jvay5jb20x\nGjAYBgNVBAMTEW5ncm9rLmNvbSByb290IGNhMB4XDTE1MDYwMjIxMDAyNloXDTI1\nMDUzMDIxMDAyNlowUjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWEx\nEjAQBgNVBAoTCW5ncm9rLmNvbTEaMBgGA1UEAxMRbmdyb2suY29tIHJvb3QgY2Ew\nggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC4bRQzcfP6CylvTp5qdfPi\n6V/Jh7DZMGGYl4q962mVDbpsLWcgYwZOFMFAi9xO20VnlkTPbtaOelG/bryznVrP\nedqe6fd8T/GZaTSjiUIpvIw5wLKdudAsjCOj9EZ0OPaxdEK4ONkiRvPQd1SdyokK\nBeKjgVYV9y+fAWXsLYQnoDbV0aFHBL4N4QXR4CoYhg7sLQLP9uF123i7rVpMWLT7\njuIMHryRNGr4AgzbSpmFrtFpWj93hcyoFLy7LRptH6jNk9BDCHLJ2ZCtr8Cdl6Jb\n4UKSzLhUEnIqppKb1R1m9vlL4SZ5WHPp7Ejjd4fhADnkQTnaa/Vgzn7sA0bFs9Mh\nAgMBAAGjgbUwgbIwHQYDVR0OBBYEFHvweCOn4+KJuYz18ySG8Cda66E+MIGCBgNV\nHSMEezB5gBR78Hgjp+PiibmM9fMkhvAnWuuhPqFWpFQwUjELMAkGA1UEBhMCVVMx\nEzARBgNVBAgTCkNhbGlmb3JuaWExEjAQBgNVBAoTCW5ncm9rLmNvbTEaMBgGA1UE\nAxMRbmdyb2suY29tIHJvb3QgY2GCCQClGIPBu4DGCDAMBgNVHRMEBTADAQH/MA0G\nCSqGSIb3DQEBBQUAA4IBAQCreihnp/LrPC8WIWz6CwkFzFaupEH/qZikTMhGc5uf\nU7CxO7fLTiPhXZRit1Jo7qviZl55JdOjpTXWmEJdj+JdoRqTNxTuea9BGot8ma7S\n9gnNwi8s5OEgNa+zO8ID2QqZ5j//uZhGOoNPjz+TwKGveeeEkHqnD0awSHGoEoLh\ng+YLj0kmU4T8MCd9xljYfm4F1Ve5ku3JmIte8oRA8ynqfQTqLiwHvbAuVVt5A5Jr\nuJshpik+/CitrhiPDN/8wFIZnUnxorB0qItHnrjVlNLh3d0G+ER309ig1UIBmTMC\nyAPV68e8DPN3Idam8AQaqPE6sK/0CtDTXebGZrfXh6g+\n-----END CERTIFICATE-----"
      },
      "https": null,
      "webhook_validation": null
    },
    {
      "id": "ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
      "type": "https",
      "description": "web frontend",
      "metadata": "",
      "created_at": "2019-07-30T02:33:02Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
      "basic_auth": null,
      "circuit_breaker": null,
      "compression": null,
      "request_headers": {
        "enabled": true,
        "headers": {
          "X-Frontend": "ngrok"
        }
      },
      "ip_policy": {
        "enabled": true,
        "ip_policies": [
          {
            "id": "ip_1OiIQyUNExbUsb8yJcNVHLRDvi8",
            "uri": "https://api.ngrok.com/ip_policies/ip_1OiIQyUNExbUsb8yJcNVHLRDvi8"
          }
        ]
      },
      "mutual_tls": null,
      "https": null,
      "webhook_validation": null
    }
  ],
  "uri": "https://api.ngrok.com/endpoint_configurations"
}

Create Endpoint Configuration

Create a new endpoint configuration

Request
POST/endpoint_configurations
Parameters
type defines the type of traffic this configuration will handle, one of http, https, tls. Requried
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
metadata arbitrary user-defined data of this endpoint configuration
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{ "type": "https", "compression": {"enabled": "true"} }' https://api.ngrok.com/endpoint_configurations
Response

Returns a 201 status code on successful creation of the endpoint configuration

Parameters
type defines the type of traffic this configuration will handle, one of http, https, or tls
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
webhook_validation object with Webhook Validation module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
created_at time of endpoint configuration creation
id unique endpoint configuration resource identifier
metadata arbitrary user-defined data of this endpoint configuration
uri URI to the API resource of the endpoint configuration
Example Response
{
      "id": "ec_1OiIPuxZMEpBJUYZlIWF37xylMg",
      "type": "https",
      "description": "",
      "metadata": "",
      "created_at": "2019-07-30T02:32:49Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OiIPuxZMEpBJUYZlIWF37xylMg",
      "basic_auth": null,
      "circuit_breaker": null,
      "compression": {
        "enabled": true
      },
      "request_headers": null,
      "ip_policy": null,
      "mutual_tls": null,
      "https": null,
      "webhook_validation": null
}

Endpoint Configuration Detail

Returns detailed information about an endpoint configuration

Request
GET/endpoint_configurations/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ
Response
Parameters
type defines the type of traffic this configuration will handle, one of http, https, or tls
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
webhook_validation object with Webhook Validation module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
created_at time of endpoint configuration creation
id unique endpoint configuration resource identifier
metadata arbitrary user-defined data of this endpoint configuration
uri URI to the API resource of the endpoint configuration
Example Response
{
  "id": "ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
  "type": "https",
  "description": "web frontend",
  "metadata": "",
  "created_at": "2019-07-30T02:33:02Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  },
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ip_1OiIQyUNExbUsb8yJcNVHLRDvi8",
        "uri": "https://api.ngrok.com/ip_policies/ip_1OiIQyUNExbUsb8yJcNVHLRDvi8"
      }
    ]
  },
  "mutual_tls": null,
  "https": null,
  "webhook_validation": null
}

Update Endpoint Configuration

Updates an endpoint configuration. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.

Request
PATCH/endpoint_configurations/:id
Parameters
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
metadata arbitrary user-defined data of this endpoint configuration
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -H "X-Ngrok-Version: 1" -d ' {"metadata": "last updated by alan", "circuit_breaker": {"error_threshold_percentage": 0.5}, "ip_policy": {"ip_policy_ids": ["ipp_1Ok0pMjiNoPV1bESvYY56ZKACge", "ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc"]} }' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ
Response
Parameters
type defines the type of traffic this configuration will handle, one of http, https, or tls
basic_auth the object with Basic Auth module parameters, or null Parameters
circuit_breaker object with Basic Auth module parameters, or null Parameters
compression object with Compression module parameters, or null Parameters
https object with HTTPS module parameters, or null Parameters
ip_policy object with IP Policy module parameters, or null Parameters
mutual_tls object with Mutual TLS module parameters, or null Parameters
request_headers object with Request Headers module parameters, or null Parameters
webhook_validation object with Webhook Validation module parameters, or null Parameters
description optional human-readable description of the endpoint configuration
created_at time of endpoint configuration creation
id unique endpoint configuration resource identifier
metadata arbitrary user-defined data of this endpoint configuration
uri URI to the API resource of the endpoint configuration
Example Response
{
  "id": "ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
  "type": "https",
  "description": "web frontend",
  "metadata": "last updated by alan",
  "created_at": "2019-07-30T02:33:02Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ",
  "basic_auth": null,
  "circuit_breaker": {
    "enabled": true,
    "tripped_duration": 10,
    "rolling_window": 10,
    "num_buckets": 10,
    "volume_threshold": 20,
    "error_threshold_percentage": 0.5
  },
  "compression": null,
  "request_headers": {
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  },
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ipp_1Ok0pMjiNoPV1bESvYY56ZKACge",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1Ok0pMjiNoPV1bESvYY56ZKACge"
      },
      {
        "id": "ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc"
      }
    ]
  },
  "mutual_tls": null,
  "https": null,
  "webhook_validation": null
}

Delete Endpoint Configuration

Delete an endpoint configuration. This operation will fail if the endpoint configuration is still referenced by any reserved domain or reserved address.

Request
DELETE/endpoint_configurations/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ
      
Response

Returns a 204 response with no body on success

Endpoint Configuration Modules

Each module presents its own subresource underneath the endpoint configuration resource. These subresources provide a more convenient mechanism to manipulate modules instead of using the PATCH method on the endpoint configuration itself. Note that the DELETE method of the subresource is the only way to remove a module (this is not possible via the PATCH call).

Each subresource exposes these methods:

  • GET to view the module details
  • PUT to replace the module's configuration
  • DELETE to remove the module from the endpoint configuration

Basic Auth Detail

Returns the state of the basic auth module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/basic_auth
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/basic_auth
Response
Parameters
Basic Authentication Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
realm an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is "ngrok"
allow_options true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
auth_provider_id determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password passed specified by the ngrok agent's -auth flag, if any.
Example Response
{
  "enabled": true,
  "auth_provider_id": "agent"
}

Replace Basic Auth

Updates the complete state of the basic auth module with new values.

Request
PUT/endpoint_configurations/:id/basic_auth
Parameters
Basic Authentication Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
realm an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is "ngrok"
allow_options true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
auth_provider_id determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password passed specified by the ngrok agent's -auth flag, if any.
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"auth_provider_id": "agent", "enabled": false}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/basic_auth
Response
Parameters
Basic Authentication Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
realm an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is "ngrok"
allow_options true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
auth_provider_id determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password passed specified by the ngrok agent's -auth flag, if any.
Example Response
{
  "enabled": false,
  "auth_provider_id": "agent"
}

Delete Basic Auth

Deletes the basic auth module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/basic_auth
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/basic_auth
Response

Returns a 204 response with no body on success

Circuit Breaker Detail

Returns the state of the circuit breaker module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/circuit_breaker
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/circuit_breaker
Response
Parameters
Circuit Breaker Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
tripped_duration Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_window Integer number of seconds in the statistical rolling window that metrics are retained for.
num_buckets Integer number of buckets into which metrics are retained. Max 128.
volume_threshold Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentage Decimal value between 0 and 1 defining the percentage at or above which the circuit should trip open and start failing requests without sending them to the upstream server.
Example Response
{
  "enabled": true,
  "tripped_duration": 10,
  "rolling_window": 10,
  "num_buckets": 10,
  "volume_threshold": 20,
  "error_threshold_percentage": 0.5
}

Replace Circuit Breaker

Updates the complete state of the circuit breaker module with new values.

Request
PUT/endpoint_configurations/:id/circuit_breaker
Parameters
Circuit Breaker Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
tripped_duration Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_window Integer number of seconds in the statistical rolling window that metrics are retained for.
num_buckets Integer number of buckets into which metrics are retained. Max 128.
volume_threshold Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentage Decimal value between 0 and 1 defining the percentage at or above which the circuit should trip open and start failing requests without sending them to the upstream server.
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"tripped_duration": 60, "rolling_window": 120, "num_buckets": 5, "volume_threshold": 20, "error_threshold_percentage": 0.2}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/circuit_breaker
Response
Parameters
Circuit Breaker Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
tripped_duration Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_window Integer number of seconds in the statistical rolling window that metrics are retained for.
num_buckets Integer number of buckets into which metrics are retained. Max 128.
volume_threshold Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentage Decimal value between 0 and 1 defining the percentage at or above which the circuit should trip open and start failing requests without sending them to the upstream server.
Example Response
{
  "enabled": true,
  "tripped_duration": 60,
  "rolling_window": 120,
  "num_buckets": 5,
  "volume_threshold": 20,
  "error_threshold_percentage": 0.2
}

Delete Circuit Breaker

Deletes the circuit breaker module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/circuit_breaker
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/circuit_breaker
Response

Returns a 204 response with no body on success

Compression Detail

Returns the state of the compression module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/compression
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/compression
Response
Parameters
Compression Module Parameters
enabled true or false indicating whether this module will compress http responses automatically
Example Response
{
  "enabled": true,
}

Replace Compression

Updates the complete state of the compression module with new values.

Request
PUT/endpoint_configurations/:id/compression
Parameters
Compression Module Parameters
enabled true or false indicating whether this module will compress http responses automatically
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"enabled": false}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/compression
Response
Parameters
Compression Module Parameters
enabled true or false indicating whether this module will compress http responses automatically
Example Response
{
  "enabled": false
}

Delete Compression

Deletes the compression module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/compression
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/compression
Response

Returns a 204 response with no body on success

HTTPS Detail

Returns the state of the HTTPS module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/https
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/https
Response
Parameters
HTTPS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
terminate_tls true or false, should TLS traffic be terminated at ngrok's edge or forwarded through unterminated
Example Response
{
  "enabled": true,
  "terminate_tls": true
}

Replace HTTPS

Updates the complete state of the HTTPS module with new values.

Request
PUT/endpoint_configurations/:id/https
Parameters
HTTPS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
terminate_tls true or false, should TLS traffic be terminated at ngrok's edge or forwarded through unterminated
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"terminate_tls": false}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/https
Response
Parameters
HTTPS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
terminate_tls true or false, should TLS traffic be terminated at ngrok's edge or forwarded through unterminated
Example Response
{
  "enabled": true,
  "terminate_tls": false
}

Delete HTTPS

Deletes the HTTPS module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/https
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/https
Response

Returns a 204 response with no body on success

IP Policy Detail

Returns the state of the ip policy module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/ip_policy
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/ip_policy
Response
Parameters
IP Policy Module Parmaeters
enabled true or false indicating whether this module will be applied to incoming traffic
ip_policies list of all IP policies that are attached to this endpoint configuration
IP Policy Object Parameters
id unique resource ID of the IP policy
uri URI to the IP Policy API resource
Example Response
{
  "ip_policies": [
    {
      "id": "ipp_1Ok0pMjiNoPV1bESvYY56ZKACge",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1Ok0pMjiNoPV1bESvYY56ZKACge"
    },
    {
      "id": "ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc"
    }
  ],
  "enabled": true
}

Replace IP Policy

Updates the complete state of the ip policy module with new values.

Request
PUT/endpoint_configurations/:id/ip_policy
Parameters
IP Policy Module Parmaeters
enabled true or false indicating whether this module will be applied to incoming traffic
ip_policy_ids a list of IP policy IDs to use for validating the source IP of incoming traffic
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"ip_policy_ids": ["ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc"]}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/ip_policy
Response
Parameters
IP Policy Module Parmaeters
enabled true or false indicating whether this module will be applied to incoming traffic
ip_policies list of all IP policies that are attached to this endpoint configuration
IP Policy Object Parameters
id unique resource ID of the IP policy
uri URI to the IP Policy API resource
Example Response
{
  "ip_policies": [
    {
      "id": "ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1Ok0pBHzvEvtMXj8ZvniUDbLiNc"
    }
  ],
  "enabled": true
}

Delete IP Policy

Deletes the ip policy module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/ip_policy
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/ip_policy
Response

Returns a 204 response with no body on success

Mutual TLS Detail

Returns the state of the mutual TLS module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/mutual_tls
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/mutual_tls
Response
Parameters
Mutual TLS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Example Response
{
  "enabled": true,
  "client_cas": "-----BEGIN CERTIFICATE-----\nMIID3TCCAsWgAwIBAgIJAKUYg8G7gMYIMA0GCSqGSIb3DQEBBQUAMFIxCzAJBgNV\nBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRIwEAYDVQQKEwluZ3Jvay5jb20x\nGjAYBgNVBAMTEW5ncm9rLmNvbSByb290IGNhMB4XDTE1MDYwMjIxMDAyNloXDTI1\nMDUzMDIxMDAyNlowUjELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWEx\nEjAQBgNVBAoTCW5ncm9rLmNvbTEaMBgGA1UEAxMRbmdyb2suY29tIHJvb3QgY2Ew\nggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC4bRQzcfP6CylvTp5qdfPi\n6V/Jh7DZMGGYl4q962mVDbpsLWcgYwZOFMFAi9xO20VnlkTPbtaOelG/bryznVrP\nedqe6fd8T/GZaTSjiUIpvIw5wLKdudAsjCOj9EZ0OPaxdEK4ONkiRvPQd1SdyokK\nBeKjgVYV9y+fAWXsLYQnoDbV0aFHBL4N4QXR4CoYhg7sLQLP9uF123i7rVpMWLT7\njuIMHryRNGr4AgzbSpmFrtFpWj93hcyoFLy7LRptH6jNk9BDCHLJ2ZCtr8Cdl6Jb\n4UKSzLhUEnIqppKb1R1m9vlL4SZ5WHPp7Ejjd4fhADnkQTnaa/Vgzn7sA0bFs9Mh\nAgMBAAGjgbUwgbIwHQYDVR0OBBYEFHvweCOn4+KJuYz18ySG8Cda66E+MIGCBgNV\nHSMEezB5gBR78Hgjp+PiibmM9fMkhvAnWuuhPqFWpFQwUjELMAkGA1UEBhMCVVMx\nEzARBgNVBAgTCkNhbGlmb3JuaWExEjAQBgNVBAoTCW5ncm9rLmNvbTEaMBgGA1UE\nAxMRbmdyb2suY29tIHJvb3QgY2GCCQClGIPBu4DGCDAMBgNVHRMEBTADAQH/MA0G\nCSqGSIb3DQEBBQUAA4IBAQCreihnp/LrPC8WIWz6CwkFzFaupEH/qZikTMhGc5uf\nU7CxO7fLTiPhXZRit1Jo7qviZl55JdOjpTXWmEJdj+JdoRqTNxTuea9BGot8ma7S\n9gnNwi8s5OEgNa+zO8ID2QqZ5j//uZhGOoNPjz+TwKGveeeEkHqnD0awSHGoEoLh\ng+YLj0kmU4T8MCd9xljYfm4F1Ve5ku3JmIte8oRA8ynqfQTqLiwHvbAuVVt5A5Jr\nuJshpik+/CitrhiPDN/8wFIZnUnxorB0qItHnrjVlNLh3d0G+ER309ig1UIBmTMC\nyAPV68e8DPN3Idam8AQaqPE6sK/0CtDTXebGZrfXh6g+\n-----END CERTIFICATE-----"
      }

Replace Mutual TLS

Updates the complete state of the mutual TLS module with new values.

Request
PUT/endpoint_configurations/:id/mutual_tls
Parameters
Mutual TLS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"client_cas": "-----BEGIN CERTIFICATE-----\nMIIBRDCB7KADAgECAhEA8zDvQr9AK22BQkptu8lqrDAKBggqhkjOPQQDAjASMRAw\nDgYDVQQKEwdBY21lIENvMB4XDTE5MDcxNzAzMjk1NVoXDTI5MDcxNDAzMjk1NVow\nEjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABDMw\njD3xzDIHhGa5HIaEPpLN2gKryh3ULMHXyObF7WRxOXl3m8eRCIbPPlEA5dx3IwuD\nrTsvZeRjO+yyGHEBl3ujIzAhMA4GA1UdDwEB/wQEAwICBDAPBgNVHRMBAf8EBTAD\nAQH/MAoGCCqGSM49BAMCA0cAMEQCIEt0nNQ8nbyDEn2VXzbGfPGDQ29chDSb/ULq\na59VOrruAiAE541zw6psskcGgzl99/O5nOtev4IGGQdqyvUrnAeeDQ==\n-----END CERTIFICATE-----", "enabled": true}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/mutual_tls
Response
Parameters
Mutual TLS Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Example Response
{
  "enabled": true,
  "client_cas": "-----BEGIN CERTIFICATE-----\nMIIBRDCB7KADAgECAhEA8zDvQr9AK22BQkptu8lqrDAKBggqhkjOPQQDAjASMRAw\nDgYDVQQKEwdBY21lIENvMB4XDTE5MDcxNzAzMjk1NVoXDTI5MDcxNDAzMjk1NVow\nEjEQMA4GA1UEChMHQWNtZSBDbzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABDMw\njD3xzDIHhGa5HIaEPpLN2gKryh3ULMHXyObF7WRxOXl3m8eRCIbPPlEA5dx3IwuD\nrTsvZeRjO+yyGHEBl3ujIzAhMA4GA1UdDwEB/wQEAwICBDAPBgNVHRMBAf8EBTAD\nAQH/MAoGCCqGSM49BAMCA0cAMEQCIEt0nNQ8nbyDEn2VXzbGfPGDQ29chDSb/ULq\na59VOrruAiAE541zw6psskcGgzl99/O5nOtev4IGGQdqyvUrnAeeDQ==\n-----END CERTIFICATE-----"
}

Delete Mutual TLS

Deletes the mutual TLS module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/mutual_tls
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/mutual_tls
Response

Returns a 204 response with no body on success

Request Headers Detail

Returns the state of the request headers module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/request_headers
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Response
{
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  }

Replace Request Headers

Updates the complete state of the request headers module with new values.

Request
PUT/endpoint_configurations/:id/request_headers
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{ "headers": {"X-Foo": "bar", "X-Baz": "qux"} }' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Response
{
    "enabled": true,
    "headers": {
      "X-Foo": "bar",
      "X-Baz": "qux",
    }
  }

Delete Request Headers

Deletes the request headers module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/request_headers
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response

Returns a 204 response with no body on success

Request Headers Detail

Returns the state of the request headers module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/request_headers
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Response
{
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  }

Replace Request Headers

Updates the complete state of the request headers module with new values.

Request
PUT/endpoint_configurations/:id/request_headers
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{ "headers": {"X-Foo": "bar", "X-Baz": "qux"} }' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response
Parameters
Request Headers
enabled true or false indicating whether this module will be applied to incoming traffic
headers a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
Example Response
{
    "enabled": true,
    "headers": {
      "X-Foo": "bar",
      "X-Baz": "qux",
    }
  }

Delete Request Headers

Deletes the request headers module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/request_headers
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/request_headers
Response

Returns a 204 response with no body on success

Webhook Validation Detail

Returns the state of the webhook validation module on the specified endpoint configuration.

Request
GET/endpoint_configurations/:id/webhook_validation
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/webhook_validation
Response
Parameters
Webhook Validation Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
provider a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
validation_information a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret.
Example Response
{
      "enabled": true,
      "provider": "SLACK",
      "secret": "jiTSkQHXOHeCuXhMOq+fhz+jThLsJGm"
  }

Replace Webhook Validation

Updates the complete state of the webhook validation module with new values.

Request
PUT/endpoint_configurations/:id/webhook_validation
Parameters
Webhook Validation Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
provider a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
validation_information a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret.
Example Request
curl -X PUT -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"enabled":true, "provider": "SNS"}' https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/webhook_validation
Response
Parameters
Webhook Validation Module Parameters
enabled true or false indicating whether this module will be applied to incoming traffic
provider a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
validation_information a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret.
Example Response
{
      "enabled": true,
      "provider": "SNS",
      "secret": ""
  }

Delete Webhook Validation

Deletes the webhook validation module from the endpoint configuration.

Request
DELETE/endpoint_configurations/:id/webhook_validation
Example Request
curl -X DELETE -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/endpoint_configurations/ec_1OiIRWu7Ya5MiMPchIPNBdcdoBQ/webhook_validation
Response

Returns a 204 response with no body on success

List IP Policies

Returns a list of all ip policies for your account

Request
GET/ip_policies
Response
Parameters
ip_policies the list of ip policies for this account
IP Policy Object Parameters
type the IP policy type. The only current supported value is whitelist
description optional description of the source IPs of this IP policy
created_at time of IP Policy creation
id unique IP Policy resource identifier
metadata arbitrary user-defined data of this IP policy
uri URI to the API resource of the IP policy
Example Response
{
  "ip_policies": [
    {
      "id": "ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw",
      "created_at": "2019-07-28T07:34:50Z",
      "description": "API Outbound Gateway",
      "metadata": "",
      "type": "whitelist"
    },
    {
      "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS",
      "created_at": "2019-07-28T07:35:30Z",
      "description": "Developer Environments",
      "metadata": "",
      "type": "whitelist"
    }
  ],
  "uri": "https://api.ngrok.com/ip_policies"
}

Create IP Policy

Create a new IP policy for your account.

Request
POST/ip_policies
Parameters
description human-readable description of the IP policy. Usually describing the source IP rules. Optional, max 255 bytes.
metadata arbitrary user-defined data of this IP policy. Optional, max 4096 bytes.
type the type of this IP policy. Currently, the only supported value is whitelist
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"type": "whitelist", "description":"API Outbound Gateway"}' https://api.ngrok.com/ip_policies
Response

Returns a 201 status code on successful creation of the ip policy

Parameters
type the IP policy type. The only current supported value is whitelist
description optional description of the source IPs of this IP policy
created_at time of IP Policy creation
id unique IP Policy resource identifier
metadata arbitrary user-defined data of this IP policy
uri URI to the API resource of the IP policy
Example Response
{
  "id": "ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS",
  "created_at": "2019-07-28T07:35:30Z",
  "description": "API Outbound Gateway",
  "metadata": "",
  "type": "whitelist"
}

IP Policy Detail

Returns detailed information about an ip policy

Request
GET/ip_policies/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS
Response
Parameters
type the IP policy type. The only current supported value is whitelist
description optional description of the source IPs of this IP policy
created_at time of IP Policy creation
id unique IP Policy resource identifier
metadata arbitrary user-defined data of this IP policy
uri URI to the API resource of the IP policy
Example Response
{
  "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS",
  "created_at": "2019-07-28T07:35:30Z",
  "description": "Developer Environments",
  "metadata": "",
  "type": "whitelist"
}

Update IP Policy

Updates attributes of an IP Policy record

Request
PATCH/ip_policies/:id
Parameters
description human-readable description of the IP policy. Usually describing the source IP rules. Optional, max 255 bytes.
metadata arbitrary user-defined data of this IP policy. Optional, max 4096 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'metadata={"pod-id": "b3d9c464-4f48-4783-a741-d7d7d5db310f"}' https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS
Response
Parameters
type the IP policy type. The only current supported value is whitelist
description optional description of the source IPs of this IP policy
created_at time of IP Policy creation
id unique IP Policy resource identifier
metadata arbitrary user-defined data of this IP policy
uri URI to the API resource of the IP policy
Example Response
{
  "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS",
  "created_at": "2019-07-28T07:35:30Z",
  "description": "Developer Environments",
  "metadata": "{\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}",
  "type": "whitelist"
}

Delete IP Policy

Delete an IP Policy from your account.

Request
DELETE/ip_policies/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS
Response

Returns a 204 response with no body on success

List IP Policy Rules

Returns a list of all ip policy rules for your account

Request
GET/ip_policy_rules
Response
Parameters
ip_policy_rules the list of all ip policy for this account
IP Policy Rule Object Parameters
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
description optional description of the IP Policy Rule
created_at time of IP Policy Rule creation
ip_policy object describing the IP policy this IP Policy Rule belongs to
id unique IP Policy Rule resource identifier
metadata arbitrary user-defined data of this IP policy rule
uri URI to the API resource of the IP policy rule
IP Policy Object Parameters
id ID of the ip policy this IP policy rule belongs to
uri URI to the API resource of the IP policy this IP policy rule belongs to
Example Response
{
  "ip_policy_rules": [
    {
      "id": "ipr_1OdEukvWUW1fTwdCfae9SLqVv2Y",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OdEukvWUW1fTwdCfae9SLqVv2Y",
      "created_at": "2019-07-28T07:34:57Z",
      "description": "alan laptop",
      "metadata": "",
      "cidr": "2.2.2.2/32",
      "ip_policy": {
        "id": "ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw"
      }
    },
    {
      "id": "ipr_1OfDmx9MCFUxd3uRoxYv9p0Ekuu",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OfDmx9MCFUxd3uRoxYv9p0Ekuu",
      "created_at": "2019-07-29T00:25:19Z",
      "description": "sf office",
      "metadata": "",
      "cidr": "132.2.19.0/24",
      "ip_policy": {
        "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS"
      }
    },
    {
      "id": "ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
      "created_at": "2019-07-29T00:25:48Z",
      "description": "nyc office",
      "metadata": "",
      "cidr": "212.3.14.0/24",
      "ip_policy": {
        "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS"
      }
    }
  ],
  "uri": "https://api.ngrok.com/ip_policy_rules"
}

Create IP Policy Rule

Create a new IP policy rule on a specified IP policy.

Request
POST/ip_policy_rules
Parameters
cidr an IP or IP range in CIDR notation. IPv4 and IPv6 are both supported.
description human-readable description of the IP policy rule. Usually describing the source IP. Optional, max 255 bytes.
ip_policy_id ID of the IP policy this IP policy rule will be attached to
metadata arbitrary user-defined data of this IP policy rule. Optional, max 4096 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"ip_policy_id": "ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw", "description":"alan laptop"}' https://api.ngrok.com/ip_policy_rules
      
Response

Returns a 201 status code on successful creation of the ip policy rule

Parameters
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
description optional description of the IP Policy Rule
created_at time of IP Policy Rule creation
ip_policy object describing the IP policy this IP Policy Rule belongs to
id unique IP Policy Rule resource identifier
metadata arbitrary user-defined data of this IP policy rule
uri URI to the API resource of the IP policy rule
IP Policy Object Parameters
id ID of the ip policy this IP policy rule belongs to
uri URI to the API resource of the IP policy this IP policy rule belongs to
Example Response
{
  "id": "ipr_1OdEukvWUW1fTwdCfae9SLqVv2Y",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OdEukvWUW1fTwdCfae9SLqVv2Y",
  "created_at": "2019-07-28T07:34:57Z",
  "description": "alan laptop",
  "metadata": "",
  "cidr": "2.2.2.2/32",
  "ip_policy": {
    "id": "ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEtsBfjLEzzIdTp0Ji2AX9okw"
  }
}

IP Policy Rule Detail

Returns detailed information about an ip policy rule

Request
GET/ip_policy_rules/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF
Response
Parameters
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
description optional description of the IP Policy Rule
created_at time of IP Policy Rule creation
ip_policy object describing the IP policy this IP Policy Rule belongs to
id unique IP Policy Rule resource identifier
metadata arbitrary user-defined data of this IP policy rule
uri URI to the API resource of the IP policy rule
IP Policy Object Parameters
id ID of the ip policy this IP policy rule belongs to
uri URI to the API resource of the IP policy this IP policy rule belongs to
Example Response
{
  "id": "ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
  "created_at": "2019-07-29T00:25:48Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS"
  }
}

Update IP Policy Rule

Updates attributes of an IP Policy rule

Request
PATCH/ip_policy_rules/:id
Parameters
cidr an IP or IP range in CIDR notation. IPv4 and IPv6 are both supported.
description human-readable description of the IP policy rule. Usually describing the source IP. Optional, max 255 bytes.
metadata arbitrary user-defined data of this IP policy rule. Optional, max 4096 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'metadata={"pod-id": "b3d9c464-4f48-4783-a741-d7d7d5db310f"}' https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF
Response
Parameters
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
description optional description of the IP Policy Rule
created_at time of IP Policy Rule creation
ip_policy object describing the IP policy this IP Policy Rule belongs to
id unique IP Policy Rule resource identifier
metadata arbitrary user-defined data of this IP policy rule
uri URI to the API resource of the IP policy rule
IP Policy Object Parameters
id ID of the ip policy this IP policy rule belongs to
uri URI to the API resource of the IP policy this IP policy rule belongs to
Example Response
{
  "id": "ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF",
  "created_at": "2019-07-29T00:25:48Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_1OdEyu4kpdrq2604Shu40XecNFS",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1OdEyu4kpdrq2604Shu40XecNFS"
  }
}

Delete IP Policy Rule

Delete an IP policy rule from the account

Request
DELETE/ip_policy_rules/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/ip_policy_rules/ipr_1OfDqXQk1ZkDsItGkMFSMA8LzMF
Response

Returns a 204 response with no body on success

List IP Whitelist

Returns a list of all IP Whitelist entries for your account

Request
GET/ip_whitelist
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/ip_whitelist
Response
Parameters
whitelist the list of whitelist entries for this account
IP Whitelist Entry Object Parameters
ip_net the IP network and mask in CIDR notation to whitelist
created_at time of IP whitelist entry creation as an ISO-8601 timestamp
description human-readable description of this IP whitelist entry
id unique IP whitelist entry resource identifier
metadata arbitrary user-defined data of this IP whitelist entry
uri URI to the API resource of the IP whitelist entry
Example Response
{
  "whitelist": [
      {
          "ip_net": "10.1.1.0/24",
          "created_at": "2015-01-02T13:49:21Z",
          "description": "outbound proxy servers",
          "id": "wl_85PtDp9AjRaESHPatReaNx",
          "metadata": "",
          "uri": "https://api.ngrok.com/ip_whitelist/wl_85PtDp9AjRaESHPatReaNx"
      },
      {
          "ip_net": "78.3.12.121",
          "created_at": "2015-01-02T13:49:21Z",
          "description": "office wifi",
          "id": "wl_iZvL6L8CR2oDF3Jj23yvoi",
          "metadata": "",
          "uri": "https://api.ngrok.com/ip_whitelist/wl_iZvL6L8CR2oDF3Jj23yvoi"
      }
  ],
  "uri": "https://api.ngrok.com/ip_whitelist"
}

Create IP Whitelist Entry

Whitelist a new IP or IP network for your account

Request
POST/ip_whitelist
Example Request
Parameters
ip_net whitelist this IP address (e.g. 10.1.1.1) or an IP network range given in CIDR notation (e.g. '10.1.0.0/16)
description human-readable description of this IP whitelist entry. Optional, max 255 bytes.
metadata arbitrary user-defined data of this IP whitelist entry. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d "ip_net=12.1.1.1" https://api.ngrok.com/ip_whitelist
Response

Returns a 201 status code on successful creation of a whitelist entry

Parameters
ip_net the IP network and mask in CIDR notation to whitelist
created_at time of IP whitelist entry creation as an ISO-8601 timestamp
description human-readable description of this IP whitelist entry
id unique IP whitelist entry resource identifier
metadata arbitrary user-defined data of this IP whitelist entry
uri URI to the API resource of the IP whitelist entry
Example Response
{
  "ip_net": "12.1.1.1/32",
  "created_at": "2015-01-02T13:49:21Z",
  "description": "",
  "id": "wl_85PtDp9AjRaESHPatReaNx",
  "metadata": "",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_85PtDp9AjRaESHPatReaNx"
}

IP Whitelist Entry Detail

Returns detailed information about a whitelist entry

Request
GET/ip_whitelist/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/ip_whitelist/wl_85PtDp9AjRaESHPatReaNx
Response
Parameters
ip_net the IP network and mask in CIDR notation to whitelist
created_at time of IP whitelist entry creation as an ISO-8601 timestamp
description human-readable description of this IP whitelist entry
id unique IP whitelist entry resource identifier
metadata arbitrary user-defined data of this IP whitelist entry
uri URI to the API resource of the IP whitelist entry
Example Response
{
  "ip_net": "12.1.1.1/32",
  "created_at": "2015-01-02T13:49:21Z",
  "description": "",
  "id": "wl_85PtDp9AjRaESHPatReaNx",
  "metadata": "",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_85PtDp9AjRaESHPatReaNx"
}

Update IP Whitelist Entry

Update attributes of an IP whitelist entry record

Request
PATCH/ip_whitelist/:id
Example Request
Parameters
description human-readable description of this IP whitelist entry. Optional, max 255 bytes.
metadata arbitrary user-defined data of this IP whitelist entry. Optional, max 4096 bytes.
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'description=home office for alan&metadata={"type": "home office", "employee_name": "alan"}' https://api.ngrok.com/ip_whitelist/wl_mCPUgaQGGUkWYAhhUUbD82
Response

Returns a 200 status code on successful update of the IP whitelist entry

Parameters
ip_net the IP network and mask in CIDR notation to whitelist
created_at time of IP whitelist entry creation as an ISO-8601 timestamp
description human-readable description of this IP whitelist entry
id unique IP whitelist entry resource identifier
metadata arbitrary user-defined data of this IP whitelist entry
uri URI to the API resource of the IP whitelist entry
Example Response
{
  "ip_net": "80.19.2.202/32",
  "created_at": "2015-01-02T13:49:21Z",
  "description": "home office for alan",
  "id": "wl_mCPUgaQGGUkWYAhhUUbD82",
  "metadata": "{\"type\": \"home office\", \"employee_name\": \"alan\"}",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_mCPUgaQGGUkWYAhhUUbD82"
}

Delete IP Whitelist Entry

Delete an IP whitelist entry

Request
DELETE/ip_whitelist/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/ip_whitelist/wl_mCPUgaQGGUkWYAhhUUbD82
Response

Returns a 204 response with no body on success

List SSH Credentials

Returns a list of all ssh credentials for your account

Request
GET/ssh_credentials
Response
Parameters
ssh_credentials the list of ssh credentials for this account
SSH Credential Object Parameters
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
description optional description of who or what uses the SSH credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this SSH credential is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of SSH credential creation
id unique SSH credential resource identifier
metadata arbitrary user-defined data of this SSH credential
uri URI to the API resource of the SSH credential
Example Response
{
  "ssh_credentials": [
      {
          "acl": [
              "bind:1.tcp.ngrok.io.dev:20001",
              "bind:129.devices.company.com"
          ],
          "created_at": "2015-02-06T22:45:14Z",
          "description": "for device #129",
          "id": "sshcr_1OdHO4spKzXLYINlBsKVF3gg1mT",
          "metadata": "",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDq6n0LSNwPZCUUXLBlKqVEr/89cd+x1s3ZwSMHeMpoRehzJLYk9O9WUumHA+XtpQwreDsgnrU8YQIaq8VU7hdujl5RVpvnBhLuwVh7gcdu6su3JQJDXj2Km1Xl+bhnzxTL/gZr4l4P9H3RkfLj6/KDSUb0KzhQ/VcdbsRSkWFeiDrAt/uIlENFhPdGuHnNN2dXfCFMv6JDmg7u4YPNyB79ZsjBjUKvFNa2v+p+UkaDfCLmuKKRgiR/k5Lju919rN5CnohsekujxkbDLumymCLNCVO22eJ+RbO0Xylul44AFnCvPyK1INBAC/cAJ3Uo1H4yOKDk+eI2lQaWN+sbnA77 device129@example.com",
          "uri": "https://api.ngrok.com/credentials/sshcr_1OdHO4spKzXLYINlBsKVF3gg1mT"
      },
      {
          "acl": [
              "bind:1.tcp.ngrok.io.dev:20002",
              "bind:132.devices.company.com"
          ],
          "created_at": "2015-03-01T17:35:58Z",
          "description": "for device #132",
          "id": "sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq",
          "metadata": "",
          "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
          "uri": "https://api.ngrok.com/credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq"
      }
  ],
  "uri": "https://api.ngrok.com/ssh_credentials"
}

Create SSH Credential

Create a new SSH credential for your account.

Request
POST/ssh_credentials
Parameters
description human-readable description of who or what will use the SSH credential to authenticate. Optional, max 255 bytes.
acl a list of ACL rules. Optional. If unspecified, the SSH credential will have all permissions. The only allowed ACL rule at this time is the bind rule. The bind rule allows you to restrict what domains and addresses the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io.
metadata arbitrary user-defined data of this SSH credential. Optional, max 4096 bytes.
public_key Public key of the SSH keypair that will be used to authenticate to the ngrok SSH tunnel servers.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -H "Content-Type: application/json" -d '{"description":"for device #132", "acl": ["bind:myname.com", "bind:1.tcp.ngrok.io:20001", "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com"]}' https://api.ngrok.com/credentials
Response

Returns a 201 status code on successful creation of the ssh credential

Parameters
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
description optional description of who or what uses the SSH credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this SSH credential is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of SSH credential creation
id unique SSH credential resource identifier
metadata arbitrary user-defined data of this SSH credential
uri URI to the API resource of the SSH credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq",
  "metadata": "",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "uri": "https://api.ngrok.com/credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq"
}

SSH Credential Detail

Returns detailed information about a ssh credential

Request
GET/ssh_credentials/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" https://api.ngrok.com/ssh_credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq
Response
Parameters
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
description optional description of who or what uses the SSH credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this SSH credential is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of SSH credential creation
id unique SSH credential resource identifier
metadata arbitrary user-defined data of this SSH credential
uri URI to the API resource of the SSH credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq",
  "metadata": "",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "uri": "https://api.ngrok.com/credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq"
}

Update SSH Credential

Updates attributes of a SSH credential record

Request
PATCH/credentials/:id
Parameters
description human-readable description of who or what will use the SSH credential to authenticate. Optional, max 255 bytes.
acl a list of ACL rules. Optional. If unspecified, the SSH credential will have all permissions. The only allowed ACL rule at this time is the bind rule. The bind rule allows you to restrict what domains and addresses the token is allowed to bind. For example, to allow the SSH credential to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io.
metadata arbitrary user-defined data of this credential. Optional, max 255 bytes.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -d 'metadata={"device-id": "03424d6b-0ffa-4eb7-96aa-60aabfad20ba"}' https://api.ngrok.com/credentials/cr_2HxDq3BuKpyEMeesbuLq8
Response
Parameters
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
description optional description of who or what uses the SSH credential to authenticate
acl a list of ACL rules that describe what actions a client connecting with this SSH credential is allowed to perform. A rule of '*' means the client may perform all actions.
created_at time of SSH credential creation
id unique SSH credential resource identifier
metadata arbitrary user-defined data of this SSH credential
uri URI to the API resource of the SSH credential
Example Response
{
  "acl": [
      "bind:1.tcp.ngrok.io.dev:20002",
      "bind:132.devices.company.com"
  ],
  "created_at": "2015-03-01T17:35:58Z",
  "description": "for device #132",
  "id": "sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq",
  "metadata": "{\"device-id\": \"03424d6b-0ffa-4eb7-96aa-60aabfad20ba\"}",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "uri": "https://api.ngrok.com/credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq"
}

Revoke SSH Credential

Revoke a ssh credential so that it may no longer be used

Request
DELETE/ssh_credentials/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "X-Ngrok-Version: 1" -XDELETE https://api.ngrok.com/ssh_credentials/sshcr_1OeHv4YfHb4hgntYwzbbWOVtQvq
Response

Returns a 204 response with no body on success