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

OAuth

Supported on type:

The OAuth module enforces an OAuth authentication flow in front of any endpoint it is enabled on. Any HTTP client accessing an OAuth-protected endpoint will be redirected to a chosen identity provider (currently Google, Microsoft, Github or Facebook) for authentication. When they are redirected back to the protected endpoint, ngrok will check a series of authorization constraints that allow you to define who is authorized to access the resource by setting a list of email addresses, email domains and other requirements. If the user is authorized, their request will be forwarded through to the upstream server and ngrok's edge will set an HTTP cookie on their browser session to keep them logged in so that the authentication flow is not repeated.

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.

Response Headers

Supported on types: ,

The Response Headers module allows you to specify a set of key/value pairs that will be injected as headers into the HTTP response before it is returned to the caller. It is especially useful for enforcing the use of security headers on all responses returned by your application.

If a specified header key already exists in an HTTP response, 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.

TLS Certificates

ngrok supports uploading your own TLS certificates which we will use to terminate traffic to a given reserved domain at the ngrok edge. You may wish to use this functionality in addition to our automatically provisioned certificates if you are using an EV cert or provisioning certificates from your own certificate authority. Uploading a certificate will not change any traffic, you must then attach the certificate to a reserved domain by setting the certificate_id property on the reserved domain with the ID of the certificate you'd like to use for TLS termination.

Certificate Bundles

When uploading a new certificate to ngrok via the API, the certificate_pem field expects a certificate bundle of all certificates necessary to establish a chain of trust to a trusted root certificate authority. Many TLS certificate vendors will provide you with a constructed certificate bundle, but some will return the leaf certificate and the intermediate certificates separately and you must concatenate them to construct the bundle yourself.

Certificate bundles are a series of PEM-encoded X.509 certificates that have been concatenated together in a specific order. A bundle will look like the following:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
      

The first certificate in the bundle must be the leaf certificate. You can think of the leaf certificate as the one which is signed for your domain and the private key you will upload.

After the leaf are the intermediates certificates, if any. Each intermediate signs the certificate preceding it in the bundle. As an example, the first intermediate will have signed the leaf, and that signature is part of the leaf certificate itself. The final certificate is signed by the root certificate. You may also included the root certificate in the bundle as well, but it is not necessary or common practice to do so.

Private Keys

ngrok accepts the following formats for the private_key_pem field:

All of the above (PKCS#1, PKCS#8, and SEC 1) are represented with ASN.1 DER (a binary format), encoded as PEM.

ngrok will not accept any private keys that are encrypted (e.g. with DES)..

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

Create API Key

Create a new API key. The generated API key can be used to authenticateto the ngrok API.

Request
POST/api_keys
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"ad-hoc dev testing","metadata":"{\"environment\":\"dev\"}"}' \
https://api.ngrok.com/api_keys
Parameters
description human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. optional, max 4096 bytes
Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "uri": "https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2020-04-03T16:15:35Z",
  "token": "1a2P5wpl7QZAVHXGr5B6aEQoJAe_3L33UmN4izGLm8RYDxT15"
}
Fields
id unique API key resource identifier
uri URI to the API resource of this API key
description human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at timestamp when the api key was created, RFC 3339 format
token the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

Delete API Key

Delete an API key by ID

Request
DELETE/api_keys/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe
Response

Returns a 204 response with no body on success

Get API Key

Get the details of an API key by ID.

Request
GET/api_keys/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe
Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "uri": "https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2020-04-03T16:15:35Z",
  "token": null
}
Fields
id unique API key resource identifier
uri URI to the API resource of this API key
description human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at timestamp when the api key was created, RFC 3339 format
token the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

List API Keys

List all API keys owned by this account

Request
GET/api_keys
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/api_keys
Response

Returns a 200 response on success

Example Response
{
  "keys": [
    {
      "id": "ak_1a2P5oQ5ZvzMPTEPGRnjtjb1VET",
      "uri": "https://api.ngrok.com/api_keys/ak_1a2P5oQ5ZvzMPTEPGRnjtjb1VET",
      "description": "api key for example generation",
      "metadata": "",
      "created_at": "2020-04-03T16:15:34Z",
      "token": null
    },
    {
      "id": "ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
      "uri": "https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
      "description": "ad-hoc dev testing",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2020-04-03T16:15:35Z",
      "token": null
    }
  ],
  "uri": "https://api.ngrok.com/api_keys"
}
Fields
keys the list of API keys for this account
uri URI of the API keys list API resource

Update API Key

Update attributes of an API key by ID.

Request
PATCH/api_keys/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"metadata":"{\"environment\":\"dev\", \"owner_id\": 123}"}' \
https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe
Parameters
description human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. optional, max 4096 bytes
Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "uri": "https://api.ngrok.com/api_keys/ak_1a2P5wpl7QZAVHXGr5B6aEQoJAe",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2020-04-03T16:15:35Z",
  "token": null
}
Fields
id unique API key resource identifier
uri URI to the API resource of this API key
description human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at timestamp when the api key was created, RFC 3339 format
token the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.

Create Abuse Report

Creates a new abuse report which will be reviewed by our system and abuse response team. This API is only available to authorized accounts. Contact abuse@ngrok.com to request access

Request
POST/abuse_reports
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"urls":["http://legit-facebook-login.ngrok.io/login"],"metadata":"{\"incident_id\":1233122}"}' \
https://api.ngrok.com/abuse_reports
Parameters
urls a list of URLs containing suspected abusive content
metadata arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.
Response

Returns a 200 response on success

Example Response
{
  "id": "abrp_1a2P6SaI4PtPkOd0flM1eZ7HTJ4",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1a2P6SaI4PtPkOd0flM1eZ7HTJ4",
  "created_at": "2020-04-03T16:15:39Z",
  "urls": [
    "http://legit-facebook-login.ngrok.io/login"
  ],
  "metadata": "{\"incident_id\":1233122}",
  "status": "PROCESSED",
  "hostnames": [
    {
      "hostname": "legit-facebook-login.ngrok.io",
      "status": "BANNED"
    }
  ]
}
Fields
id ID of the abuse report
uri URI of the abuse report API resource
created_at timestamp that the abuse report record was created in RFC 3339 format
urls a list of URLs containing suspected abusive content
metadata arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.
status Indicates whether ngrok has processed the abuse report. one of PENDING, PROCESSED, or PARTIALLY_PROCESSED
hostnames an array of hostname statuses related to the report

Get Abuse Report

Get the detailed status of abuse report by ID.

Request
GET/abuse_reports/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/abuse_reports/abrp_1a2P6SaI4PtPkOd0flM1eZ7HTJ4
Response

Returns a 200 response on success

Example Response
{
  "id": "abrp_1a2P6SaI4PtPkOd0flM1eZ7HTJ4",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1a2P6SaI4PtPkOd0flM1eZ7HTJ4",
  "created_at": "2020-04-03T16:15:39Z",
  "urls": [
    "http://legit-facebook-login.ngrok.io/login"
  ],
  "metadata": "{\"incident_id\":1233122}",
  "status": "PROCESSED",
  "hostnames": [
    {
      "hostname": "legit-facebook-login.ngrok.io",
      "status": "BANNED"
    }
  ]
}
Fields
id ID of the abuse report
uri URI of the abuse report API resource
created_at timestamp that the abuse report record was created in RFC 3339 format
urls a list of URLs containing suspected abusive content
metadata arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.
status Indicates whether ngrok has processed the abuse report. one of PENDING, PROCESSED, or PARTIALLY_PROCESSED
hostnames an array of hostname statuses related to the report

Create Endpoint Configuration

Create a new endpoint configuration

Request
POST/endpoint_configurations
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"type":"https","description":"app servers","request_headers":{"headers":{"X-Frontend":"ngrok"}}}' \
https://api.ngrok.com/endpoint_configurations
Parameters
type they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp
description human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
metadata arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
basic_auth basic auth module configuration or null
circuit_breaker circuit breaker module configuration or null
compression compression module configuration or null
request_headers request headers module configuration or null
response_headers response headers module configuration or null
ip_policy ip policy module configuration or null
mutual_tls mutual TLS module configuration or null
https HTTPS module configuration or null
webhook_validation webhook validation module configuration or null
oauth oauth module configuration or null
Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2020-04-03T16:15:35Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  },
  "response_headers": null,
  "ip_policy": null,
  "mutual_tls": null,
  "https": null,
  "webhook_validation": null,
  "oauth": null
}
Fields
id unique identifier of this endpoint configuration
type they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp
description human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
metadata arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
created_at timestamp when the endpoint configuration was created, RFC 3339 format
uri URI of the endpoint configuration API resource
basic_auth basic auth module configuration or null
circuit_breaker circuit breaker module configuration or null
compression compression module configuration or null
request_headers request headers module configuration or null
response_headers response headers module configuration or null
ip_policy ip policy module configuration or null
mutual_tls mutual TLS module configuration or null
https HTTPS module configuration or null
webhook_validation webhook validation module configuration or null
oauth oauth module configuration or 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 \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ
Response

Returns a 204 response with no body on success

Get Endpoint Configuration

Returns detailed information about an endpoint configuration

Request
GET/endpoint_configurations/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ
Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2020-04-03T16:15:35Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  },
  "response_headers": null,
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ipp_1a2P5tLimwQCr0wl0HDVgAuYX31",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5tLimwQCr0wl0HDVgAuYX31"
      }
    ]
  },
  "mutual_tls": null,
  "https": null,
  "webhook_validation": null,
  "oauth": null
}
Fields
id unique identifier of this endpoint configuration
type they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp
description human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
metadata arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
created_at timestamp when the endpoint configuration was created, RFC 3339 format
uri URI of the endpoint configuration API resource
basic_auth basic auth module configuration or null
circuit_breaker circuit breaker module configuration or null
compression compression module configuration or null
request_headers request headers module configuration or null
response_headers response headers module configuration or null
ip_policy ip policy module configuration or null
mutual_tls mutual TLS module configuration or null
https HTTPS module configuration or null
webhook_validation webhook validation module configuration or null
oauth oauth module configuration or null

List Endpoint Configurations

Returns a list of all endpoint configurations on this account

Request
GET/endpoint_configurations
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations
Response

Returns a 200 response on success

Example Response
{
  "endpoint_configurations": [
    {
      "id": "ec_1a2P5wVPJRdPdTjkfbaZcj63e2H",
      "type": "https",
      "description": "web servers",
      "metadata": "",
      "created_at": "2020-04-03T16:15:35Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5wVPJRdPdTjkfbaZcj63e2H",
      "basic_auth": null,
      "circuit_breaker": {
        "enabled": true,
        "tripped_duration": 0,
        "rolling_window": 0,
        "num_buckets": 0,
        "volume_threshold": 0,
        "error_threshold_percentage": 0.2
      },
      "compression": {
        "enabled": true
      },
      "request_headers": null,
      "response_headers": {
        "enabled": true,
        "headers": {
          "Content-Security-Policy": "script-src 'self'",
          "X-Frame-Options": "DENY"
        }
      },
      "ip_policy": null,
      "mutual_tls": null,
      "https": null,
      "webhook_validation": null,
      "oauth": null
    },
    {
      "id": "ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
      "type": "https",
      "description": "app servers",
      "metadata": "",
      "created_at": "2020-04-03T16:15:35Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
      "basic_auth": null,
      "circuit_breaker": null,
      "compression": null,
      "request_headers": {
        "enabled": true,
        "headers": {
          "X-Frontend": "ngrok"
        }
      },
      "response_headers": null,
      "ip_policy": null,
      "mutual_tls": null,
      "https": null,
      "webhook_validation": null,
      "oauth": null
    }
  ],
  "uri": "https://api.ngrok.com/endpoint_configurations"
}
Fields
endpoint_configurations the list of all endpoint configurations on this account
uri URI of the endpoint configurations list API resource

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}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"ip_policy":{"ip_policy_ids":["ipp_1a2P5tLimwQCr0wl0HDVgAuYX31"]}}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ
Parameters
description human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
metadata arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
basic_auth basic auth module configuration or null
circuit_breaker circuit breaker module configuration or null
compression compression module configuration or null
request_headers request headers module configuration or null
response_headers response headers module configuration or null
ip_policy ip policy module configuration or null
mutual_tls mutual TLS module configuration or null
https HTTPS module configuration or null
webhook_validation webhook validation module configuration or null
oauth oauth module configuration or null
Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2020-04-03T16:15:35Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5x87t8C886MHYHAu1n1zrUZ",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "headers": {
      "X-Frontend": "ngrok"
    }
  },
  "response_headers": null,
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ipp_1a2P5tLimwQCr0wl0HDVgAuYX31",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5tLimwQCr0wl0HDVgAuYX31"
      }
    ]
  },
  "mutual_tls": null,
  "https": null,
  "webhook_validation": null,
  "oauth": null
}
Fields
id unique identifier of this endpoint configuration
type they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp
description human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
metadata arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
created_at timestamp when the endpoint configuration was created, RFC 3339 format
uri URI of the endpoint configuration API resource
basic_auth basic auth module configuration or null
circuit_breaker circuit breaker module configuration or null
compression compression module configuration or null
request_headers request headers module configuration or null
response_headers response headers module configuration or null
ip_policy ip policy module configuration or null
mutual_tls mutual TLS module configuration or null
https HTTPS module configuration or null
webhook_validation webhook validation module configuration or null
oauth oauth module configuration or null

Replace Basic Auth Module

Request
PUT/endpoint_configurations/{id}/basic_auth
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"auth_provider_id":"agent","allow_options":true}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/basic_auth
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 specified by the ngrok agent's -auth flag, if any.
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
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "auth_provider_id": "agent",
  "realm": "",
  "allow_options": true
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 specified by the ngrok agent's -auth flag, if any.
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

Get Basic Auth Module

Request
GET/endpoint_configurations/{id}/basic_auth
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/basic_auth
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "auth_provider_id": "agent",
  "realm": "",
  "allow_options": true
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 specified by the ngrok agent's -auth flag, if any.
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

Delete Basic Auth Module

Request
DELETE/endpoint_configurations/{id}/basic_auth
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/basic_auth
Response

Returns a 204 response with no body on success

Replace Circuit Breaker Module

Request
PUT/endpoint_configurations/{id}/circuit_breaker
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"tripped_duration":120,"rolling_window":300,"num_buckets":5,"volume_threshold":20,"error_threshold_percentage":0.2}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/circuit_breaker
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 Error threshold percentage should be between 0 - 1.0, not 0-100.0
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "tripped_duration": 120,
  "rolling_window": 300,
  "num_buckets": 5,
  "volume_threshold": 20,
  "error_threshold_percentage": 0.2
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 Error threshold percentage should be between 0 - 1.0, not 0-100.0

Get Circuit Breaker Module

Request
GET/endpoint_configurations/{id}/circuit_breaker
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/circuit_breaker
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "tripped_duration": 120,
  "rolling_window": 300,
  "num_buckets": 5,
  "volume_threshold": 20,
  "error_threshold_percentage": 0.2
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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 Error threshold percentage should be between 0 - 1.0, not 0-100.0

Delete Circuit Breaker Module

Request
DELETE/endpoint_configurations/{id}/circuit_breaker
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/circuit_breaker
Response

Returns a 204 response with no body on success

Replace Compression Module

Request
PUT/endpoint_configurations/{id}/compression
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"enabled":false}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/compression
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
Response

Returns a 200 response on success

Example Response
{
  "enabled": false
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified

Get Compression Module

Request
GET/endpoint_configurations/{id}/compression
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/compression
Response

Returns a 200 response on success

Example Response
{
  "enabled": false
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified

Delete Compression Module

Request
DELETE/endpoint_configurations/{id}/compression
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/compression
Response

Returns a 204 response with no body on success

Replace HTTPS Module

Request
PUT/endpoint_configurations/{id}/https
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"terminate_tls":true,"min_tls_version":"1.2"}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/https
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_tls true if the ngrok edge should terminate TLS traffic, false if TLS traffic should be passed through to the upstream server. if false, most other modules will not be allowed because they rely on being able to access the underlying traffic.
min_tls_version The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "terminate_tls": true,
  "min_tls_version": "1.2"
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_tls true if the ngrok edge should terminate TLS traffic, false if TLS traffic should be passed through to the upstream server. if false, most other modules will not be allowed because they rely on being able to access the underlying traffic.
min_tls_version The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default

Get HTTPS Module

Request
GET/endpoint_configurations/{id}/https
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/https
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "terminate_tls": true,
  "min_tls_version": "1.2"
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_tls true if the ngrok edge should terminate TLS traffic, false if TLS traffic should be passed through to the upstream server. if false, most other modules will not be allowed because they rely on being able to access the underlying traffic.
min_tls_version The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default

Delete HTTPS Module

Request
DELETE/endpoint_configurations/{id}/https
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/https
Response

Returns a 204 response with no body on success

Replace IP Policy Module

Request
PUT/endpoint_configurations/{id}/ip_policy
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"ip_policy_ids":["ipp_1a2P6SNl5PAhGQvRjGNTtSrNgat"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/ip_policy
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
ip_policy_ids list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_1a2P6SNl5PAhGQvRjGNTtSrNgat",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6SNl5PAhGQvRjGNTtSrNgat"
    }
  ]
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
ip_policies

Get IP Policy Module

Request
GET/endpoint_configurations/{id}/ip_policy
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/ip_policy
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_1a2P6SNl5PAhGQvRjGNTtSrNgat",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6SNl5PAhGQvRjGNTtSrNgat"
    }
  ]
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
ip_policies

Delete IP Policy Module

Request
DELETE/endpoint_configurations/{id}/ip_policy
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/ip_policy
Response

Returns a 204 response with no body on success

Replace Mutual TLS Module

Request
PUT/endpoint_configurations/{id}/mutual_tls
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"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://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/mutual_tls
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Response

Returns a 200 response on success

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-----",
  "certs": [
    {
      "common_name": "ngrok.com root ca",
      "issuer": "ngrok.com root ca",
      "not_before": "2015-06-02T21:00:26Z",
      "not_after": "2025-05-30T21:00:26Z",
      "serial_number": "pRiDwbuAxgg=",
      "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuG0UM3Hz+gspb06eanXz4ulfyYew2TBhmJeKvetplQ26bC1nIGMGThTBQIvcTttFZ5ZEz27WjnpRv268s51az3nanun3fE/xmWk0o4lCKbyMOcCynbnQLIwjo/RGdDj2sXRCuDjZIkbz0HdUncqJCgXio4FWFfcvnwFl7C2EJ6A21dGhRwS+DeEF0eAqGIYO7C0Cz/bhddt4u61aTFi0+47iDB68kTRq+AIM20qZha7RaVo/d4XMqBS8uy0abR+ozZPQQwhyydmQra/AnZeiW+FCksy4VBJyKqaSm9UdZvb5S+EmeVhz6exI43eH4QA55EE52mv1YM5+7ANGxbPTIQIDAQAB",
      "sha256_fingerprint": "d391xo2Lxy+FNhOFgxGnOoTLRv8Mkr7P9LrZ8QIpLGw=",
      "alternative_names": null
    }
  ]
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
certs a list of objects with detailed information about the parsed client CA roots in client_cas

Get Mutual TLS Module

Request
GET/endpoint_configurations/{id}/mutual_tls
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/mutual_tls
Response

Returns a 200 response on success

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-----",
  "certs": [
    {
      "common_name": "ngrok.com root ca",
      "issuer": "ngrok.com root ca",
      "not_before": "2015-06-02T21:00:26Z",
      "not_after": "2025-05-30T21:00:26Z",
      "serial_number": "pRiDwbuAxgg=",
      "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuG0UM3Hz+gspb06eanXz4ulfyYew2TBhmJeKvetplQ26bC1nIGMGThTBQIvcTttFZ5ZEz27WjnpRv268s51az3nanun3fE/xmWk0o4lCKbyMOcCynbnQLIwjo/RGdDj2sXRCuDjZIkbz0HdUncqJCgXio4FWFfcvnwFl7C2EJ6A21dGhRwS+DeEF0eAqGIYO7C0Cz/bhddt4u61aTFi0+47iDB68kTRq+AIM20qZha7RaVo/d4XMqBS8uy0abR+ozZPQQwhyydmQra/AnZeiW+FCksy4VBJyKqaSm9UdZvb5S+EmeVhz6exI43eH4QA55EE52mv1YM5+7ANGxbPTIQIDAQAB",
      "sha256_fingerprint": "d391xo2Lxy+FNhOFgxGnOoTLRv8Mkr7P9LrZ8QIpLGw=",
      "alternative_names": null
    }
  ]
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
client_cas PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
certs a list of objects with detailed information about the parsed client CA roots in client_cas

Delete Mutual TLS Module

Request
DELETE/endpoint_configurations/{id}/mutual_tls
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/mutual_tls
Response

Returns a 204 response with no body on success

Replace OAuth Module

Request
PUT/endpoint_configurations/{id}/oauth
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"provider":{"google":{"client_id":"client-id","client_secret":"client-secret","scopes":["profile","email","https://www.googleapis.com/auth/gmail.compose"],"email_addresses":["alan@example.com"]}},"options_passthrough":true}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/oauth
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
provider an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok'
inactivity_timeout Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration Integer number of seconds of the maximum duration an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "provider": {
    "github": null,
    "facebook": null,
    "microsoft": null,
    "google": {
      "client_id": "client-id",
      "client_secret": "client-secret",
      "scopes": [
        "profile",
        "email",
        "https://www.googleapis.com/auth/gmail.compose"
      ],
      "email_addresses": [
        "alan@example.com"
      ],
      "email_domains": null
    }
  },
  "options_passthrough": true,
  "cookie_prefix": "",
  "inactivity_timeout": null,
  "maximum_duration": null,
  "auth_check_interval": 0
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
provider an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok'
inactivity_timeout Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration Integer number of seconds of the maximum duration an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

Get OAuth Module

Request
GET/endpoint_configurations/{id}/oauth
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/oauth
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "provider": {
    "github": null,
    "facebook": null,
    "microsoft": null,
    "google": {
      "client_id": "client-id",
      "client_secret": "client-secret",
      "scopes": [
        "profile",
        "email",
        "https://www.googleapis.com/auth/gmail.compose"
      ],
      "email_addresses": [
        "alan@example.com"
      ],
      "email_domains": null
    }
  },
  "options_passthrough": true,
  "cookie_prefix": "",
  "inactivity_timeout": null,
  "maximum_duration": null,
  "auth_check_interval": 0
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
provider an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok'
inactivity_timeout Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration Integer number of seconds of the maximum duration an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

Delete OAuth Module

Request
DELETE/endpoint_configurations/{id}/oauth
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/oauth
Response

Returns a 204 response with no body on success

Replace Request Headers Module

Request
PUT/endpoint_configurations/{id}/request_headers
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"headers":{"X-Baz":"qux","X-Foo":"bar"}}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/request_headers
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "headers": {
    "X-Baz": "qux",
    "X-Foo": "bar"
  }
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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

Get Request Headers Module

Request
GET/endpoint_configurations/{id}/request_headers
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/request_headers
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "headers": {
    "X-Baz": "qux",
    "X-Foo": "bar"
  }
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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

Delete Request Headers Module

Request
DELETE/endpoint_configurations/{id}/request_headers
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/request_headers
Response

Returns a 204 response with no body on success

Replace Response Headers Module

Request
PUT/endpoint_configurations/{id}/response_headers
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"headers":{"Cache-Control":"no-cache, no-store","X-XSS-Protection":"1; mode=block"}}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/response_headers
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
headers a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "headers": {
    "Cache-Control": "no-cache, no-store",
    "X-Xss-Protection": "1; mode=block"
  }
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
headers a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

Get Response Headers Module

Request
GET/endpoint_configurations/{id}/response_headers
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/response_headers
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "headers": {
    "Cache-Control": "no-cache, no-store",
    "X-Xss-Protection": "1; mode=block"
  }
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
headers a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

Delete Response Headers Module

Request
DELETE/endpoint_configurations/{id}/response_headers
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/response_headers
Response

Returns a 204 response with no body on success

Replace Webhook Validation Module

Request
PUT/endpoint_configurations/{id}/webhook_validation
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"provider":"TWILIO","secret":"secret_token"}' \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/webhook_validation
Parameters
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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.
secret a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "provider": "TWILIO",
  "secret": "secret_token"
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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.
secret a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Get Webhook Validation Module

Request
GET/endpoint_configurations/{id}/webhook_validation
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/webhook_validation
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "provider": "TWILIO",
  "secret": "secret_token"
}
Fields
enabled true if the module will be applied to traffic, false to disable. default true if unspecified
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.
secret a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Delete Webhook Validation Module

Request
DELETE/endpoint_configurations/{id}/webhook_validation
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/endpoint_configurations/ec_1a2P6PjzwH9evREk4mTLmOAdq7A/webhook_validation
Response

Returns a 204 response with no body on success

Create IP Policy

Create a new IP policy. It will not apply to any traffic until you associate to a traffic source via an endpoint configuration or IP restriction.

Request
POST/ip_policies
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"API Outbound Gateway","type":"whitelist"}' \
https://api.ngrok.com/ip_policies
Parameters
description human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
type the IP policy type. The only current supported value is whitelist
Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "created_at": "2020-04-03T16:15:34Z",
  "description": "API Outbound Gateway",
  "metadata": "",
  "type": "whitelist"
}
Fields
id unique identifier for this IP policy
uri URI of the IP Policy API resource
created_at timestamp when the IP policy was created, RFC 3339 format
description human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
type the IP policy type. The only current supported value is whitelist

Delete IP Policy

Delete an IP policy. If the IP policy is referenced by another object for the purposes of traffic restriction it will be treated as if the IP policy remains but has zero rules.

Request
DELETE/ip_policies/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze
Response

Returns a 204 response with no body on success

Get IP Policy

Get detailed information about an IP policy by ID.

Request
GET/ip_policies/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze
Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "created_at": "2020-04-03T16:15:34Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}",
  "type": "whitelist"
}
Fields
id unique identifier for this IP policy
uri URI of the IP Policy API resource
created_at timestamp when the IP policy was created, RFC 3339 format
description human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
type the IP policy type. The only current supported value is whitelist

List IP Policies

List all IP policies on this account

Request
GET/ip_policies
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policies
Response

Returns a 200 response on success

Example Response
{
  "ip_policies": [
    {
      "id": "ipp_1a2P5m8bGf9BTcInwLNqvadURoG",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5m8bGf9BTcInwLNqvadURoG",
      "created_at": "2020-04-03T16:15:34Z",
      "description": "Developer Environments",
      "metadata": "",
      "type": "whitelist"
    },
    {
      "id": "ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
      "created_at": "2020-04-03T16:15:34Z",
      "description": "API Outbound Gateway",
      "metadata": "",
      "type": "whitelist"
    }
  ],
  "uri": "https://api.ngrok.com/ip_policies"
}
Fields
ip_policies the list of all IP policies on this account
uri URI of the IP policy list API resource

Update IP Policy

Update attributes of an IP policy by ID

Request
PATCH/ip_policies/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"metadata":"metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}"}' \
https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze
Parameters
description human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P5lql8Dhe6YKrRV33vlvP2Ze",
  "created_at": "2020-04-03T16:15:34Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}",
  "type": "whitelist"
}
Fields
id unique identifier for this IP policy
uri URI of the IP Policy API resource
created_at timestamp when the IP policy was created, RFC 3339 format
description human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
type the IP policy type. The only current supported value is whitelist

Create IP Policy Rule

Create a new IP policy rule attached to an IP Policy.

Request
POST/ip_policy_rules
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"nyc office","cidr":"212.3.14.0/24","ip_policy_id":"ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"}' \
https://api.ngrok.com/ip_policy_rules
Parameters
description human-readable description of the source IPs of this IP rule. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
ip_policy_id ID of the IP policy this IP policy rule will be attached to
Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
  }
}
Fields
id unique identifier for this IP policy rule
uri URI of the IP policy rule API resource
created_at timestamp when the IP policy rule was created, RFC 3339 format
description human-readable description of the source IPs of this IP rule. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
ip_policy object describing the IP policy this IP Policy Rule belongs to

Delete IP Policy Rule

Delete an IP policy rule.

Request
DELETE/ip_policy_rules/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb
Response

Returns a 204 response with no body on success

Get IP Policy Rule

Get detailed information about an IP policy rule by ID.

Request
GET/ip_policy_rules/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb
Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
  }
}
Fields
id unique identifier for this IP policy rule
uri URI of the IP policy rule API resource
created_at timestamp when the IP policy rule was created, RFC 3339 format
description human-readable description of the source IPs of this IP rule. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
ip_policy object describing the IP policy this IP Policy Rule belongs to

List IP Policy Rules

List all IP policy rules on this account

Request
GET/ip_policy_rules
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_policy_rules
Response

Returns a 200 response on success

Example Response
{
  "ip_policy_rules": [
    {
      "id": "ipr_1a2P6PrZZlyjMVUbX2D5F5w48ep",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PrZZlyjMVUbX2D5F5w48ep",
      "created_at": "2020-04-03T16:15:39Z",
      "description": "alan laptop",
      "metadata": "",
      "cidr": "2.2.2.2/32",
      "ip_policy": {
        "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
      }
    },
    {
      "id": "ipr_1a2P6SXxAsluz3TuNqnwxVe6SEo",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6SXxAsluz3TuNqnwxVe6SEo",
      "created_at": "2020-04-03T16:15:39Z",
      "description": "sf office",
      "metadata": "",
      "cidr": "132.2.19.0/24",
      "ip_policy": {
        "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
      }
    },
    {
      "id": "ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
      "created_at": "2020-04-03T16:15:39Z",
      "description": "nyc office",
      "metadata": "",
      "cidr": "212.3.14.0/24",
      "ip_policy": {
        "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
      }
    }
  ],
  "uri": "https://api.ngrok.com/ip_policy_rules"
}
Fields
ip_policy_rules the list of all IP policy rules on this account
uri URI of the IP policy rule list API resource

Update IP Policy Rule

Update attributes of an IP policy rule by ID

Request
PATCH/ip_policy_rules/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"cidr":"212.3.15.0/24"}' \
https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb
Parameters
description human-readable description of the source IPs of this IP rule. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1a2P6PXdJDVBz2CGXzkrw6UfUsb",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6U7kmOUxU0cKHYaoDEcXb6Y"
  }
}
Fields
id unique identifier for this IP policy rule
uri URI of the IP policy rule API resource
created_at timestamp when the IP policy rule was created, RFC 3339 format
description human-readable description of the source IPs of this IP rule. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.
cidr an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.
ip_policy object describing the IP policy this IP Policy Rule belongs to

Create IP Restriction

Create a new IP restriction

Request
POST/ip_restrictions
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"type":"dashboard","ip_policy_ids":["ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL"]}' \
https://api.ngrok.com/ip_restrictions
Parameters
description human-readable description of this IP restriction. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced true if the IP restriction will be enforce. if false, only warnings will be issued
type the type of IP restriction. this defines what traffic will be restricted with the attached policies. two values are currently supported: dashboard, and api
ip_policy_ids
Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL"
    }
  ]
}
Fields
id unique identifier for this IP restriction
uri URI of the IP restriction API resource
created_at timestamp when the IP restriction was created, RFC 3339 format
description human-readable description of this IP restriction. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced true if the IP restriction will be enforce. if false, only warnings will be issued
type the type of IP restriction. this defines what traffic will be restricted with the attached policies. two values are currently supported: dashboard, and api
ip_policies the set of IP policies that are used to enforce the restriction

Delete IP Restriction

Delete an IP restriction

Request
DELETE/ip_restrictions/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u
Response

Returns a 204 response with no body on success

Get IP Restriction

Get detailed information about an IP restriction

Request
GET/ip_restrictions/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u
Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL"
    },
    {
      "id": "ipp_1a2P6YSafeL1BePrtHCoZgRw5jW",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YSafeL1BePrtHCoZgRw5jW"
    }
  ]
}
Fields
id unique identifier for this IP restriction
uri URI of the IP restriction API resource
created_at timestamp when the IP restriction was created, RFC 3339 format
description human-readable description of this IP restriction. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced true if the IP restriction will be enforce. if false, only warnings will be issued
type the type of IP restriction. this defines what traffic will be restricted with the attached policies. two values are currently supported: dashboard, and api
ip_policies the set of IP policies that are used to enforce the restriction

List IP Restrictions

List all IP restrictions on this account

Request
GET/ip_restrictions
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_restrictions
Response

Returns a 200 response on success

Example Response
{
  "ip_restrictions": [
    {
      "id": "ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
      "uri": "https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
      "created_at": "2020-04-03T16:15:40Z",
      "description": "",
      "metadata": "",
      "enforced": false,
      "type": "dashboard",
      "ip_policies": [
        {
          "id": "ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL",
          "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL"
        }
      ]
    }
  ],
  "uri": "https://api.ngrok.com/ip_restrictions"
}
Fields
ip_restrictions the list of all IP restrictions on this account
uri URI of the IP resrtrictions list API resource

Update IP Restriction

Update attributes of an IP restriction by ID

Request
PATCH/ip_restrictions/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"ip_policy_ids":["ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL","ipp_1a2P6YSafeL1BePrtHCoZgRw5jW"]}' \
https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u
Parameters
description human-readable description of this IP restriction. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced true if the IP restriction will be enforce. if false, only warnings will be issued
ip_policy_ids
Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1a2P6bmYzX81BYGSv2Lcbza4j7u",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YmzxlvzF1Vk3pmqQs5wHaL"
    },
    {
      "id": "ipp_1a2P6YSafeL1BePrtHCoZgRw5jW",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1a2P6YSafeL1BePrtHCoZgRw5jW"
    }
  ]
}
Fields
id unique identifier for this IP restriction
uri URI of the IP restriction API resource
created_at timestamp when the IP restriction was created, RFC 3339 format
description human-readable description of this IP restriction. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced true if the IP restriction will be enforce. if false, only warnings will be issued
type the type of IP restriction. this defines what traffic will be restricted with the attached policies. two values are currently supported: dashboard, and api
ip_policies the set of IP policies that are used to enforce the restriction

Create IP Whitelist Entry

Create a new IP whitelist entry that will restrict traffic to all tunnel endpoints on the account.

Request
POST/ip_whitelist
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"outbound proxy servers","ip_net":"10.1.1.0/24"}' \
https://api.ngrok.com/ip_whitelist
Parameters
description human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
Response

Returns a 200 response on success

Example Response
{
  "id": "wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "outbound proxy servers",
  "metadata": "",
  "ip_net": "10.1.1.0/24"
}
Fields
id unique identifier for this IP whitelist entry
uri URI of the IP whitelist entry API resource
created_at timestamp when the IP whitelist entry was created, RFC 3339 format
description human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

Delete IP Whitelist Entry

Delete an IP whitelist entry.

Request
DELETE/ip_whitelist/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev
Response

Returns a 204 response with no body on success

Get IP Whitelist Entry

Get detailed information about an IP whitelist entry by ID.

Request
GET/ip_whitelist/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev
Response

Returns a 200 response on success

Example Response
{
  "id": "wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "home office for alan",
  "metadata": "{\"type\": \"home office\", \"employee_name\": \"alan\"}",
  "ip_net": "10.1.1.0/24"
}
Fields
id unique identifier for this IP whitelist entry
uri URI of the IP whitelist entry API resource
created_at timestamp when the IP whitelist entry was created, RFC 3339 format
description human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

List IP Whitelist

List all IP whitelist entries on this account

Request
GET/ip_whitelist
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ip_whitelist
Response

Returns a 200 response on success

Example Response
{
  "whitelist": [
    {
      "id": "wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
      "uri": "https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
      "created_at": "2020-04-03T16:15:39Z",
      "description": "outbound proxy servers",
      "metadata": "",
      "ip_net": "10.1.1.0/24"
    },
    {
      "id": "wl_1a2P6Rg82hm1L98JCVdzkxFzALe",
      "uri": "https://api.ngrok.com/ip_whitelist/wl_1a2P6Rg82hm1L98JCVdzkxFzALe",
      "created_at": "2020-04-03T16:15:39Z",
      "description": "office wifi",
      "metadata": "",
      "ip_net": "78.3.12.121/32"
    }
  ],
  "uri": "https://api.ngrok.com/ip_whitelist"
}
Fields
whitelist the list of all IP whitelist entries on this account
uri URI of the IP whitelist API resource

Update IP Whitelist Entry

Update attributes of an IP whitelist entry by ID

Request
PATCH/ip_whitelist/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"home office for alan","metadata":"{\"type\": \"home office\", \"employee_name\": \"alan\"}"}' \
https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev
Parameters
description human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
Response

Returns a 200 response on success

Example Response
{
  "id": "wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1a2P6SaNQZavZFzZ2dDZ9U9LDev",
  "created_at": "2020-04-03T16:15:39Z",
  "description": "home office for alan",
  "metadata": "{\"type\": \"home office\", \"employee_name\": \"alan\"}",
  "ip_net": "10.1.1.0/24"
}
Fields
id unique identifier for this IP whitelist entry
uri URI of the IP whitelist entry API resource
created_at timestamp when the IP whitelist entry was created, RFC 3339 format
description human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

Create Reserved Address

Create a new reserved address.

Request
POST/reserved_addrs
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"SSH for device #001","region":"us"}' \
https://api.ngrok.com/reserved_addrs
Parameters
description human-readable description of what this reserved address will be used for
metadata arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.
region reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
endpoint_configuration_id ID of an endpoint configuration of type tcp that will be used to handle inbound traffic to this address
Response

Returns a 200 response on success

Example Response
{
  "id": "ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "SSH for device #001",
  "metadata": "",
  "addr": "1.tcp.ngrok.io:20010",
  "region": "us",
  "endpoint_configuration": null
}
Fields
id unique reserved address resource identifier
uri URI of the reserved address API resource
created_at timestamp when the reserved address was created, RFC 3339 format
description human-readable description of what this reserved address will be used for
metadata arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.
addr hostname:port of the reserved address that was assigned at creation time
region reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
endpoint_configuration object reference to the endpoint configuration that will be applied to traffic to this address

Delete Reserved Address

Delete a reserved address.

Request
DELETE/reserved_addrs/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt
Response

Returns a 204 response with no body on success

Get Reserved Address

Get the details of a reserved address.

Request
GET/reserved_addrs/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt
Response

Returns a 200 response on success

Example Response
{
  "id": "ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20010",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1a2P5si7oI91d9pPamzLtrPvpMK",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5si7oI91d9pPamzLtrPvpMK"
  }
}
Fields
id unique reserved address resource identifier
uri URI of the reserved address API resource
created_at timestamp when the reserved address was created, RFC 3339 format
description human-readable description of what this reserved address will be used for
metadata arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.
addr hostname:port of the reserved address that was assigned at creation time
region reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
endpoint_configuration object reference to the endpoint configuration that will be applied to traffic to this address

List Reserved Addresses

List all reserved addresses on this account.

Request
GET/reserved_addrs
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_addrs
Response

Returns a 200 response on success

Example Response
{
  "reserved_addrs": [
    {
      "id": "ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
      "uri": "https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
      "created_at": "2020-04-03T16:15:35Z",
      "description": "SSH for device #001",
      "metadata": "",
      "addr": "1.tcp.ngrok.io:20010",
      "region": "us",
      "endpoint_configuration": null
    }
  ],
  "uri": "https://api.ngrok.com/reserved_addrs"
}
Fields
reserved_addrs the list of all reserved addresses on this account
uri URI of the reserved address list API resource

Update Reserved Address

Update the attributes of a reserved address.

Request
PATCH/reserved_addrs/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"metadata":"{\"proto\": \"ssh\"}","endpoint_configuration_id":"ec_1a2P5si7oI91d9pPamzLtrPvpMK"}' \
https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt
Parameters
description human-readable description of what this reserved address will be used for
metadata arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.
endpoint_configuration_id ID of an endpoint configuration of type tcp that will be used to handle inbound traffic to this address
Response

Returns a 200 response on success

Example Response
{
  "id": "ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1ZzCrhNjxv9nGs4V52F1NxKrdvt",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20010",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1a2P5si7oI91d9pPamzLtrPvpMK",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5si7oI91d9pPamzLtrPvpMK"
  }
}
Fields
id unique reserved address resource identifier
uri URI of the reserved address API resource
created_at timestamp when the reserved address was created, RFC 3339 format
description human-readable description of what this reserved address will be used for
metadata arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.
addr hostname:port of the reserved address that was assigned at creation time
region reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
endpoint_configuration object reference to the endpoint configuration that will be applied to traffic to this address

Create Reserved Domain

Create a new reserved domain.

Request
POST/reserved_domains
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"name":"myapp","region":"us"}' \
https://api.ngrok.com/reserved_domains
Parameters
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.
region reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
description human-readable description of what this reserved domain will be used for
metadata arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 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
certificate_id ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
certificate_management_policy configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.
Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "",
  "metadata": "",
  "domain": "myapp.ngrok.io",
  "region": "us",
  "cname_target": null,
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "certificate": null,
  "certificate_management_policy": null,
  "certificate_management_status": null
}
Fields
id unique reserved domain resource identifier
uri URI of the reserved domain API resource
created_at timestamp when the reserved domain was created, RFC 3339 format
description human-readable description of what this reserved domain will be used for
metadata arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domain hostname of the reserved domain
region reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_target DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
http_endpoint_configuration object referencing the endpoint configuration applied to http traffic on this domain
https_endpoint_configuration object referencing the endpoint configuration applied to https traffic on this domain
certificate object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
certificate_management_policy configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status status of the automatic certificate management for this domain, or null if automatic management is disabled

Delete Reserved Domain

Delete a reserved domain.

Request
DELETE/reserved_domains/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO
Response

Returns a 204 response with no body on success

Get Reserved Domain

Get the details of a reserved domain.

Request
GET/reserved_domains/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO
Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "point-of-sale new york #302",
  "metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
  "domain": "myapp.ngrok.io",
  "region": "us",
  "cname_target": null,
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": {
    "id": "ec_1a2P5zBE3Jozf2mXPxNvI1xs0mG",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5zBE3Jozf2mXPxNvI1xs0mG"
  },
  "certificate": null,
  "certificate_management_policy": null,
  "certificate_management_status": null
}
Fields
id unique reserved domain resource identifier
uri URI of the reserved domain API resource
created_at timestamp when the reserved domain was created, RFC 3339 format
description human-readable description of what this reserved domain will be used for
metadata arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domain hostname of the reserved domain
region reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_target DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
http_endpoint_configuration object referencing the endpoint configuration applied to http traffic on this domain
https_endpoint_configuration object referencing the endpoint configuration applied to https traffic on this domain
certificate object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
certificate_management_policy configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status status of the automatic certificate management for this domain, or null if automatic management is disabled

List Reserved Domains

List all reserved domains on this account.

Request
GET/reserved_domains
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/reserved_domains
Response

Returns a 200 response on success

Example Response
{
  "reserved_domains": [
    {
      "id": "rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
      "created_at": "2020-04-03T16:15:35Z",
      "description": "",
      "metadata": "",
      "domain": "myapp.ngrok.io",
      "region": "us",
      "cname_target": null,
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": null,
      "certificate_management_policy": null,
      "certificate_management_status": null
    },
    {
      "id": "rd_1a2P60AcU9N7aN6XjB6BCSaX7LR",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1a2P60AcU9N7aN6XjB6BCSaX7LR",
      "created_at": "2020-04-03T16:15:35Z",
      "description": "Device 0001 Dashboard",
      "metadata": "{\"service\": \"dashboard\"}",
      "domain": "manage-0001.app.example.com",
      "region": "us",
      "cname_target": "2bsxabpc1.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": null,
      "certificate_management_policy": null,
      "certificate_management_status": null
    }
  ],
  "uri": "https://api.ngrok.com/reserved_domains"
}
Fields
reserved_domains the list of all reserved domains on this account
uri URI of the reserved domain list API resource

Update Reserved Domain

Update the attributes of a reserved domain.

Request
PATCH/reserved_domains/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"point-of-sale new york #302","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}","https_endpoint_configuration_id":"ec_1a2P5zBE3Jozf2mXPxNvI1xs0mG"}' \
https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO
Parameters
description human-readable description of what this reserved domain will be used for
metadata arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 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
certificate_id ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
certificate_management_policy configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.
Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1a2P5vf8dHdWBeMTuWcRhiQN5jO",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "point-of-sale new york #302",
  "metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
  "domain": "myapp.ngrok.io",
  "region": "us",
  "cname_target": null,
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": {
    "id": "ec_1a2P5zBE3Jozf2mXPxNvI1xs0mG",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1a2P5zBE3Jozf2mXPxNvI1xs0mG"
  },
  "certificate": null,
  "certificate_management_policy": null,
  "certificate_management_status": null
}
Fields
id unique reserved domain resource identifier
uri URI of the reserved domain API resource
created_at timestamp when the reserved domain was created, RFC 3339 format
description human-readable description of what this reserved domain will be used for
metadata arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domain hostname of the reserved domain
region reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_target DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
http_endpoint_configuration object referencing the endpoint configuration applied to http traffic on this domain
https_endpoint_configuration object referencing the endpoint configuration applied to https traffic on this domain
certificate object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
certificate_management_policy configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status status of the automatic certificate management for this domain, or null if automatic management is disabled

Create SSH Credential

Create a new ssh_credential from an uploaded public SSH key. This ssh credential can be used to start new tunnels via ngrok's SSH gateway.

Request
POST/ssh_credentials
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"for device #132","acl":["bind:1.tcp.ngrok.io:20002","bind:132.devices.company.com"],"public_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com"}' \
https://api.ngrok.com/ssh_credentials
Parameters
description human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
Response

Returns a 200 response on success

Example Response
{
  "id": "sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "created_at": "2020-04-03T16:15:38Z",
  "description": "for device #132",
  "metadata": "",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "acl": [
    "bind:1.tcp.ngrok.io:20002",
    "bind:132.devices.company.com"
  ]
}
Fields
id unique ssh credential resource identifier
uri URI of the ssh credential API resource
created_at timestamp when the ssh credential was created, RFC 3339 format
description human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

Delete SSH Credential

Delete an ssh_credential by ID

Request
DELETE/ssh_credentials/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os
Response

Returns a 204 response with no body on success

Get SSH Credential

Get detailed information about an ssh_credential

Request
GET/ssh_credentials/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os
Response

Returns a 200 response on success

Example Response
{
  "id": "sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "created_at": "2020-04-03T16:15:38Z",
  "description": "my dev machine",
  "metadata": "{\"hostname\": \"macbook.local\"}",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "acl": [
    "bind:1.tcp.ngrok.io:20002",
    "bind:132.devices.company.com"
  ]
}
Fields
id unique ssh credential resource identifier
uri URI of the ssh credential API resource
created_at timestamp when the ssh credential was created, RFC 3339 format
description human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

List SSH Credentials

List all ssh credentials on this account

Request
GET/ssh_credentials
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/ssh_credentials
Response

Returns a 200 response on success

Example Response
{
  "ssh_credentials": [
    {
      "id": "sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
      "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
      "created_at": "2020-04-03T16:15:38Z",
      "description": "for device #132",
      "metadata": "",
      "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
      "acl": [
        "bind:1.tcp.ngrok.io:20002",
        "bind:132.devices.company.com"
      ]
    }
  ],
  "uri": "https://api.ngrok.com/ssh_credentials"
}
Fields
ssh_credentials the list of all ssh credentials on this account
uri URI of the ssh credential list API resource

Update SSH Credential

Update attributes of an ssh_credential by ID

Request
PATCH/ssh_credentials/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"my dev machine","metadata":"{\"hostname\": \"macbook.local\"}"}' \
https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os
Parameters
description human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
Response

Returns a 200 response on success

Example Response
{
  "id": "sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1a2P6HHzcvC7VlxtaQaYkH643Os",
  "created_at": "2020-04-03T16:15:38Z",
  "description": "my dev machine",
  "metadata": "{\"hostname\": \"macbook.local\"}",
  "public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDmGS49FkSODAcKhn3+/47DW2zEn19BZvzRQ8RZjL3v6hCIX2qXfsFK35EGxNI0wV23H4xXC2gVRPHKU71YnCb50tad3yMBTM6+2yfGsEDasEH/anmBLclChKvuGiT547RskZlpbAbdq3GvbzmY+R/2EBRMOiObpc8XmSzKAd05j28kqN0+rZO65SWId0MXdvJdSCSAnuRqBNd/aXKlu8hBPDcgwbT2lMkuR+ApoBS2FLRBOiQyt2Ol0T7Uuf7lTLlazpGB3uTw5zFYUNXkuuI6cAP8QYuY1Bne/hNrG8t3Aw9a1yc2C4Fz1hJ/4OMRxTQ8SUQf+Rmxs8DryMlMFJ8r device132@example.com",
  "acl": [
    "bind:1.tcp.ngrok.io:20002",
    "bind:132.devices.company.com"
  ]
}
Fields
id unique ssh credential resource identifier
uri URI of the ssh credential API resource
created_at timestamp when the ssh credential was created, RFC 3339 format
description human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

Create TLS Certificate

Upload a new TLS certificate

Request
POST/tls_certificates
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"certificate_pem":"-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIUBUunDdA4gjgtEbZA8w9Ljhvl3bEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wHhcNMjAwMzI0MTgxODE5WhcNMjAw\nNDIzMTgxODE5WjAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAPKVkkKYNl3d9cqrz4tIFlwsohED5W4y1dcBixy4\nGANFFnw43nc2wPyKwYXumJqJIFrcW/NkUZL07bd+dou6mT6Gh/zbaTW91IkREPXL\n7b3KfVu4XkFosVXpWs0U6o4GrZ81CLiKBWI+H03x/ij5OSiJ1l71pqLeTJLOydAR\nAl8kpp7axeHU4UbDrAZkW5SnuZTjIKwVg0UNsBg1yNfUOu1Uah3BYaqPgQitC0Yg\nLW+NUGu/T91bkD7tLsVInkQXeQGdXBAqOycfJ7wj8OlIpyuXjTnGFA0izVmbQw5f\nrQnZ0geGyhLamvz9Gcd7mIlD/+/AEN9Lht82tAOzKG98/O8CAwEAAaNTMFEwHQYD\nVR0OBBYEFKv6RsvEC6T+zCtJZwB0FCR1sEkhMB8GA1UdIwQYMBaAFKv6RsvEC6T+\nzCtJZwB0FCR1sEkhMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB\nAC5fBrouinespo5+9AipjhY/HOKTg+OCnppFnSnqeU1eXZZJ0oakdHTpTNxtbQP9\ntOJTA2f3KWvmpNDMohEQXZz8wHDkdbrIXJKVp6zs1pEp+0BIjA4y9mSywa5xuyk0\noGeChRgGqp2JujDyPCb7LEaKKQEEdMqy73QG+jEAh14+wKixlAf1nATBdeCUvssK\n2x1uZMyqjJFB5y/5EdnWQzD4WJkrsCkxsZHVMN1d+dqf2sf3dTRV8fzsFGOG17NS\n6u2n9iGcFdBA82XN8yeLIWhy1t3GWutG1sdxENbFRRXea+iUqzDsmRtkaBma2GLQ\nd6JTpFbsCtwDjP23UEi7SZo=\n-----END CERTIFICATE-----","private_key_pem":"-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDylZJCmDZd3fXK\nq8+LSBZcLKIRA+VuMtXXAYscuBgDRRZ8ON53NsD8isGF7piaiSBa3FvzZFGS9O23\nfnaLupk+hof822k1vdSJERD1y+29yn1buF5BaLFV6VrNFOqOBq2fNQi4igViPh9N\n8f4o+TkoidZe9aai3kySzsnQEQJfJKae2sXh1OFGw6wGZFuUp7mU4yCsFYNFDbAY\nNcjX1DrtVGodwWGqj4EIrQtGIC1vjVBrv0/dW5A+7S7FSJ5EF3kBnVwQKjsnHye8\nI/DpSKcrl405xhQNIs1Zm0MOX60J2dIHhsoS2pr8/RnHe5iJQ//vwBDfS4bfNrQD\nsyhvfPzvAgMBAAECggEBALLv7YE98exvi5zB+0fMFuJK8gkHDLequ93q/4hhqyTO\nU3WyJTdepiAi4fk/NEXZnIopPZJdj2aNUMQnfp43OE7MwYac+hBwRFQOyKnmkSmM\nMcf0SWKKLTUn+piIMzQsbOmhHxuwg6QiGslOFaJ3o9fpRL2rCg3dWDJ6Ypcd1NgE\nK0uy7gg+DwIpU6MeG6lA+HbxbGi+yd2x88Gjn9dGr7FZK34RUDooH60BCX9P8N9X\nT+n10MzzX7ZQOsLfe8FKc1/X8AybI5SYm1GMyfKD4QBt6JG4HKAjPHzBzcIpfN3d\n7BM11Imkrz7LcbUG+F23NVsi6n5IIGT1WqwCRIH2PpECgYEA/SJ5Ra4d0hUS5RYB\nzABquM3sp7JsKxCn7O5PqNLB4TgH9dXtWFhaFVB6juMGyHbvktVH0j4lps/Te0rk\nVU2zU1XxvCTFhtcCYUtNk0cRw6LH8feKiorXHdDRB33t0c47QSD/6AGOjBtxqD7B\n3ZxyR3P+7RdQopLLRFN+FHAnmzsCgYEA9VSGZDFSK+fbg4CgwkWdzuHrAXaUEv0U\novqqWd/yXB9wauEvRHnOrSgW6hFZQiatJOXx0KnalJQzohz/SLGO0MqGtwQbYWVT\nWiJgjUbNeiPEHBeUA6U55lVQr26kQSUWdXEtRbDz+hqV1K+6tTEMzaSPmJiHNgki\nlNMO2gqGQd0CgYBJ268qx5zn2UJEGWG41j5NYbg1TfgFsLxugzI2/heX0TNxZVP1\nPQI7ydmYq2ElSJ6qZxSnoX5255i7FqT8xskV/bOkw83mhAGrxb8Cw+/I90wDq8h+\nl/ggOPdkijfDybq8TBae6SVgd/l3r6f9M1KcypmNMApVBSPN8daNvBOyVQKBgQDo\nsj2utyFrx8Xsm4rf+kxOuPbBMooM4MQ8OmpuSP6G5sMofWLqHmcs0sO5TK9PEYRV\nZU3ST+ml2FSJRdvWRaRi4laZLWoTHZrL+aN/HVM0sMwIoUyhkIy0ruOTIuzlZZpB\n1xHL8qXX6nOHgw8jYdz1CUuyv6owVMXaR77kjer+eQKBgByYZlR/eNTzlot0SdFl\nIbgQ9bV7VLIo+vKzOXE3trfzRJMgUosLTp+5wdSVSW/VBdYZ7Ir3n0bbpY/dGinI\nVShxPbChhCZnhvG2lEEiekI44m5jHSA6hhtRdt/CrhL65Rw2SE5lMEe8htg1UGus\nwzLHWHBl72FjbjdhvEgrq60W\n-----END PRIVATE KEY-----"}' \
https://api.ngrok.com/tls_certificates
Parameters
description human-readable description of this TLS certificate. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.
certificate_pem chain of PEM-encoded certificates, leaf first. See Certificate Bundles.
private_key_pem private key for the TLS certificate, PEM-encoded. See Private Keys.
Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIUBUunDdA4gjgtEbZA8w9Ljhvl3bEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wHhcNMjAwMzI0MTgxODE5WhcNMjAw\nNDIzMTgxODE5WjAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAPKVkkKYNl3d9cqrz4tIFlwsohED5W4y1dcBixy4\nGANFFnw43nc2wPyKwYXumJqJIFrcW/NkUZL07bd+dou6mT6Gh/zbaTW91IkREPXL\n7b3KfVu4XkFosVXpWs0U6o4GrZ81CLiKBWI+H03x/ij5OSiJ1l71pqLeTJLOydAR\nAl8kpp7axeHU4UbDrAZkW5SnuZTjIKwVg0UNsBg1yNfUOu1Uah3BYaqPgQitC0Yg\nLW+NUGu/T91bkD7tLsVInkQXeQGdXBAqOycfJ7wj8OlIpyuXjTnGFA0izVmbQw5f\nrQnZ0geGyhLamvz9Gcd7mIlD/+/AEN9Lht82tAOzKG98/O8CAwEAAaNTMFEwHQYD\nVR0OBBYEFKv6RsvEC6T+zCtJZwB0FCR1sEkhMB8GA1UdIwQYMBaAFKv6RsvEC6T+\nzCtJZwB0FCR1sEkhMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB\nAC5fBrouinespo5+9AipjhY/HOKTg+OCnppFnSnqeU1eXZZJ0oakdHTpTNxtbQP9\ntOJTA2f3KWvmpNDMohEQXZz8wHDkdbrIXJKVp6zs1pEp+0BIjA4y9mSywa5xuyk0\noGeChRgGqp2JujDyPCb7LEaKKQEEdMqy73QG+jEAh14+wKixlAf1nATBdeCUvssK\n2x1uZMyqjJFB5y/5EdnWQzD4WJkrsCkxsZHVMN1d+dqf2sf3dTRV8fzsFGOG17NS\n6u2n9iGcFdBA82XN8yeLIWhy1t3GWutG1sdxENbFRRXea+iUqzDsmRtkaBma2GLQ\nd6JTpFbsCtwDjP23UEi7SZo=\n-----END CERTIFICATE-----\n",
  "common_name": "example.com",
  "subject_alternative_names": {
    "dns_names": [],
    "ips": []
  },
  "issued_at": null,
  "not_before": "2020-03-24T18:18:19Z",
  "not_after": "2020-04-23T18:18:19Z",
  "key_usages": [],
  "extended_key_usages": [],
  "private_key_type": "rsa"
}
Fields
id unique identifier for this TLS certificate
uri URI of the TLS certificate API resource
created_at timestamp when the TLS certificate was created, RFC 3339 format
description human-readable description of this TLS certificate. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.
certificate_pem chain of PEM-encoded certificates, leaf first. See Certificate Bundles.
common_name subject common name from the leaf of this TLS certificate
subject_alternative_names subject alternative names (SANs) from the leaf of this TLS certificate
issued_at timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded
not_before timestamp when this TLS certificate becomes valid, RFC 3339 format
not_after timestamp when this TLS certificate becomes invalid, RFC 3339 format
key_usages set of actions the private key of this TLS certificate can be used for
extended_key_usages extended set of actions the private key of this TLS certificate can be used for
private_key_type type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

Delete TLS Certificate

Delete a TLS certificate

Request
DELETE/tls_certificates/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc
Response

Returns a 204 response with no body on success

Get TLS Certificate

Get detailed information about a TLS certificate

Request
GET/tls_certificates/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc
Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "{\"example\": true}",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIUBUunDdA4gjgtEbZA8w9Ljhvl3bEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wHhcNMjAwMzI0MTgxODE5WhcNMjAw\nNDIzMTgxODE5WjAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAPKVkkKYNl3d9cqrz4tIFlwsohED5W4y1dcBixy4\nGANFFnw43nc2wPyKwYXumJqJIFrcW/NkUZL07bd+dou6mT6Gh/zbaTW91IkREPXL\n7b3KfVu4XkFosVXpWs0U6o4GrZ81CLiKBWI+H03x/ij5OSiJ1l71pqLeTJLOydAR\nAl8kpp7axeHU4UbDrAZkW5SnuZTjIKwVg0UNsBg1yNfUOu1Uah3BYaqPgQitC0Yg\nLW+NUGu/T91bkD7tLsVInkQXeQGdXBAqOycfJ7wj8OlIpyuXjTnGFA0izVmbQw5f\nrQnZ0geGyhLamvz9Gcd7mIlD/+/AEN9Lht82tAOzKG98/O8CAwEAAaNTMFEwHQYD\nVR0OBBYEFKv6RsvEC6T+zCtJZwB0FCR1sEkhMB8GA1UdIwQYMBaAFKv6RsvEC6T+\nzCtJZwB0FCR1sEkhMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB\nAC5fBrouinespo5+9AipjhY/HOKTg+OCnppFnSnqeU1eXZZJ0oakdHTpTNxtbQP9\ntOJTA2f3KWvmpNDMohEQXZz8wHDkdbrIXJKVp6zs1pEp+0BIjA4y9mSywa5xuyk0\noGeChRgGqp2JujDyPCb7LEaKKQEEdMqy73QG+jEAh14+wKixlAf1nATBdeCUvssK\n2x1uZMyqjJFB5y/5EdnWQzD4WJkrsCkxsZHVMN1d+dqf2sf3dTRV8fzsFGOG17NS\n6u2n9iGcFdBA82XN8yeLIWhy1t3GWutG1sdxENbFRRXea+iUqzDsmRtkaBma2GLQ\nd6JTpFbsCtwDjP23UEi7SZo=\n-----END CERTIFICATE-----\n",
  "common_name": "example.com",
  "subject_alternative_names": {
    "dns_names": [],
    "ips": []
  },
  "issued_at": null,
  "not_before": "2020-03-24T18:18:19Z",
  "not_after": "2020-04-23T18:18:19Z",
  "key_usages": [],
  "extended_key_usages": [],
  "private_key_type": "rsa"
}
Fields
id unique identifier for this TLS certificate
uri URI of the TLS certificate API resource
created_at timestamp when the TLS certificate was created, RFC 3339 format
description human-readable description of this TLS certificate. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.
certificate_pem chain of PEM-encoded certificates, leaf first. See Certificate Bundles.
common_name subject common name from the leaf of this TLS certificate
subject_alternative_names subject alternative names (SANs) from the leaf of this TLS certificate
issued_at timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded
not_before timestamp when this TLS certificate becomes valid, RFC 3339 format
not_after timestamp when this TLS certificate becomes invalid, RFC 3339 format
key_usages set of actions the private key of this TLS certificate can be used for
extended_key_usages extended set of actions the private key of this TLS certificate can be used for
private_key_type type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

List TLS Certificates

List all TLS certificates on this account

Request
GET/tls_certificates
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tls_certificates
Response

Returns a 200 response on success

Example Response
{
  "tls_certificates": [
    {
      "id": "cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
      "uri": "https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
      "created_at": "2020-04-03T16:15:40Z",
      "description": "",
      "metadata": "",
      "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIUBUunDdA4gjgtEbZA8w9Ljhvl3bEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wHhcNMjAwMzI0MTgxODE5WhcNMjAw\nNDIzMTgxODE5WjAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAPKVkkKYNl3d9cqrz4tIFlwsohED5W4y1dcBixy4\nGANFFnw43nc2wPyKwYXumJqJIFrcW/NkUZL07bd+dou6mT6Gh/zbaTW91IkREPXL\n7b3KfVu4XkFosVXpWs0U6o4GrZ81CLiKBWI+H03x/ij5OSiJ1l71pqLeTJLOydAR\nAl8kpp7axeHU4UbDrAZkW5SnuZTjIKwVg0UNsBg1yNfUOu1Uah3BYaqPgQitC0Yg\nLW+NUGu/T91bkD7tLsVInkQXeQGdXBAqOycfJ7wj8OlIpyuXjTnGFA0izVmbQw5f\nrQnZ0geGyhLamvz9Gcd7mIlD/+/AEN9Lht82tAOzKG98/O8CAwEAAaNTMFEwHQYD\nVR0OBBYEFKv6RsvEC6T+zCtJZwB0FCR1sEkhMB8GA1UdIwQYMBaAFKv6RsvEC6T+\nzCtJZwB0FCR1sEkhMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB\nAC5fBrouinespo5+9AipjhY/HOKTg+OCnppFnSnqeU1eXZZJ0oakdHTpTNxtbQP9\ntOJTA2f3KWvmpNDMohEQXZz8wHDkdbrIXJKVp6zs1pEp+0BIjA4y9mSywa5xuyk0\noGeChRgGqp2JujDyPCb7LEaKKQEEdMqy73QG+jEAh14+wKixlAf1nATBdeCUvssK\n2x1uZMyqjJFB5y/5EdnWQzD4WJkrsCkxsZHVMN1d+dqf2sf3dTRV8fzsFGOG17NS\n6u2n9iGcFdBA82XN8yeLIWhy1t3GWutG1sdxENbFRRXea+iUqzDsmRtkaBma2GLQ\nd6JTpFbsCtwDjP23UEi7SZo=\n-----END CERTIFICATE-----\n",
      "common_name": "example.com",
      "subject_alternative_names": {
        "dns_names": [],
        "ips": []
      },
      "issued_at": null,
      "not_before": "2020-03-24T18:18:19Z",
      "not_after": "2020-04-23T18:18:19Z",
      "key_usages": [],
      "extended_key_usages": [],
      "private_key_type": "rsa"
    }
  ],
  "uri": "https://api.ngrok.com/tls_certificates"
}
Fields
tls_certificates the list of all TLS certificates on this account
uri URI of the TLS certificates list API resource

Update TLS Certificate

Update attributes of a TLS Certificate by ID

Request
PATCH/tls_certificates/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"metadata":"{\"example\": true}"}' \
https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc
Parameters
description human-readable description of this TLS certificate. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.
Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1a2P6ZrnAaB3uUFFOcavf7TTTCc",
  "created_at": "2020-04-03T16:15:40Z",
  "description": "",
  "metadata": "{\"example\": true}",
  "certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDDTCCAfWgAwIBAgIUBUunDdA4gjgtEbZA8w9Ljhvl3bEwDQYJKoZIhvcNAQEL\nBQAwFjEUMBIGA1UEAwwLZXhhbXBsZS5jb20wHhcNMjAwMzI0MTgxODE5WhcNMjAw\nNDIzMTgxODE5WjAWMRQwEgYDVQQDDAtleGFtcGxlLmNvbTCCASIwDQYJKoZIhvcN\nAQEBBQADggEPADCCAQoCggEBAPKVkkKYNl3d9cqrz4tIFlwsohED5W4y1dcBixy4\nGANFFnw43nc2wPyKwYXumJqJIFrcW/NkUZL07bd+dou6mT6Gh/zbaTW91IkREPXL\n7b3KfVu4XkFosVXpWs0U6o4GrZ81CLiKBWI+H03x/ij5OSiJ1l71pqLeTJLOydAR\nAl8kpp7axeHU4UbDrAZkW5SnuZTjIKwVg0UNsBg1yNfUOu1Uah3BYaqPgQitC0Yg\nLW+NUGu/T91bkD7tLsVInkQXeQGdXBAqOycfJ7wj8OlIpyuXjTnGFA0izVmbQw5f\nrQnZ0geGyhLamvz9Gcd7mIlD/+/AEN9Lht82tAOzKG98/O8CAwEAAaNTMFEwHQYD\nVR0OBBYEFKv6RsvEC6T+zCtJZwB0FCR1sEkhMB8GA1UdIwQYMBaAFKv6RsvEC6T+\nzCtJZwB0FCR1sEkhMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB\nAC5fBrouinespo5+9AipjhY/HOKTg+OCnppFnSnqeU1eXZZJ0oakdHTpTNxtbQP9\ntOJTA2f3KWvmpNDMohEQXZz8wHDkdbrIXJKVp6zs1pEp+0BIjA4y9mSywa5xuyk0\noGeChRgGqp2JujDyPCb7LEaKKQEEdMqy73QG+jEAh14+wKixlAf1nATBdeCUvssK\n2x1uZMyqjJFB5y/5EdnWQzD4WJkrsCkxsZHVMN1d+dqf2sf3dTRV8fzsFGOG17NS\n6u2n9iGcFdBA82XN8yeLIWhy1t3GWutG1sdxENbFRRXea+iUqzDsmRtkaBma2GLQ\nd6JTpFbsCtwDjP23UEi7SZo=\n-----END CERTIFICATE-----\n",
  "common_name": "example.com",
  "subject_alternative_names": {
    "dns_names": [],
    "ips": []
  },
  "issued_at": null,
  "not_before": "2020-03-24T18:18:19Z",
  "not_after": "2020-04-23T18:18:19Z",
  "key_usages": [],
  "extended_key_usages": [],
  "private_key_type": "rsa"
}
Fields
id unique identifier for this TLS certificate
uri URI of the TLS certificate API resource
created_at timestamp when the TLS certificate was created, RFC 3339 format
description human-readable description of this TLS certificate. optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.
certificate_pem chain of PEM-encoded certificates, leaf first. See Certificate Bundles.
common_name subject common name from the leaf of this TLS certificate
subject_alternative_names subject alternative names (SANs) from the leaf of this TLS certificate
issued_at timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded
not_before timestamp when this TLS certificate becomes valid, RFC 3339 format
not_after timestamp when this TLS certificate becomes invalid, RFC 3339 format
key_usages set of actions the private key of this TLS certificate can be used for
extended_key_usages extended set of actions the private key of this TLS certificate can be used for
private_key_type type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

Create Tunnel Credential

Create a new tunnel authtoken credential. This authtoken credential can be used to start a new tunnel session. 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
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"development cred for alan@example.com"}' \
https://api.ngrok.com/credentials
Parameters
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
Response

Returns a 200 response on success

Example Response
{
  "id": "cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "uri": "https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "development cred for alan@example.com",
  "metadata": "",
  "token": "1a2P5ucDchkrTx79ktKzKCP1TXg_7Nqpp6BXGwvHMRytomyEH",
  "acl": []
}
Fields
id unique tunnel credential resource identifier
uri URI of the tunnel credential API resource
created_at timestamp when the tunnel credential was created, RFC 3339 format
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
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.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

Delete Tunnel Credential

Delete a tunnel authtoken credential by ID

Request
DELETE/credentials/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg
Response

Returns a 204 response with no body on success

Get Tunnel Credential

Get detailed information about a tunnel authtoken credential

Request
GET/credentials/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg
Response

Returns a 200 response on success

Example Response
{
  "id": "cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "uri": "https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "device alpha-2",
  "metadata": "{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}",
  "token": null,
  "acl": []
}
Fields
id unique tunnel credential resource identifier
uri URI of the tunnel credential API resource
created_at timestamp when the tunnel credential was created, RFC 3339 format
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
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.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

List Tunnel Credentials

List all tunnel authtoken credentials on this account

Request
GET/credentials
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/credentials
Response

Returns a 200 response on success

Example Response
{
  "credentials": [
    {
      "id": "cr_1a2P5rmC2dhxv7uO0VHADFYYvhG",
      "uri": "https://api.ngrok.com/credentials/cr_1a2P5rmC2dhxv7uO0VHADFYYvhG",
      "created_at": "2020-04-03T16:15:34Z",
      "description": "credential for 'api-examples-924f069b7f860df9@example.com'",
      "metadata": "",
      "token": "1a2P5rmC2dhxv7uO0VHADFYYvhG_39X5DTtd5uUe27ubMHP4M",
      "acl": []
    },
    {
      "id": "cr_1a2P5ugpW5RL4pp5iDHX6ycVPOi",
      "uri": "https://api.ngrok.com/credentials/cr_1a2P5ugpW5RL4pp5iDHX6ycVPOi",
      "created_at": "2020-04-03T16:15:35Z",
      "description": "for device #132",
      "metadata": "",
      "token": null,
      "acl": [
        "bind:1.tcp.ngrok.io:20002",
        "bind:132.devices.company.com"
      ]
    },
    {
      "id": "cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
      "uri": "https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
      "created_at": "2020-04-03T16:15:35Z",
      "description": "development cred for alan@example.com",
      "metadata": "",
      "token": null,
      "acl": []
    }
  ],
  "uri": "https://api.ngrok.com/credentials"
}
Fields
credentials the list of all tunnel credentials on this account
uri URI of the tunnel credential list API resource

Update Tunnel Credential

Update attributes of an tunnel authtoken credential by ID

Request
PATCH/credentials/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 1" \
-d '{"description":"device alpha-2","metadata":"{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}"}' \
https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg
Parameters
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
Response

Returns a 200 response on success

Example Response
{
  "id": "cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "uri": "https://api.ngrok.com/credentials/cr_1a2P5ucDchkrTx79ktKzKCP1TXg",
  "created_at": "2020-04-03T16:15:35Z",
  "description": "device alpha-2",
  "metadata": "{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}",
  "token": null,
  "acl": []
}
Fields
id unique tunnel credential resource identifier
uri URI of the tunnel credential API resource
created_at timestamp when the tunnel credential was created, RFC 3339 format
description human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
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.
acl optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

List Tunnel Sessions

List all online tunnel sessions running on this account.

Request
GET/tunnel_sessions
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnel_sessions
Response

Returns a 200 response on success

Example Response
{
  "tunnel_sessions": [
    {
      "agent_version": "",
      "credential": {
        "id": "cr_1a2P66ofpVoAoULLuiq1PtQySOq",
        "uri": "https://api.ngrok.com/credentials/cr_1a2P66ofpVoAoULLuiq1PtQySOq"
      },
      "id": "ts_1a2P62zt7MLgQiAxZxSrYhvrH6u",
      "ip": "10.42.0.6",
      "metadata": "",
      "os": "linux",
      "region": "us",
      "started_at": "2020-04-03T16:15:36Z",
      "transport": "ngrok/2",
      "uri": "https://api.ngrok.com/tunnel_sessions/ts_1a2P62zt7MLgQiAxZxSrYhvrH6u"
    }
  ],
  "uri": "https://api.ngrok.com/tunnel_sessions"
}
Fields
tunnel_sessions list of all tunnel sessions on this account
uri URI to the API resource of the tunnel session list

Get Tunnel Session

Get the detailed status of a tunnel session by ID

Request
GET/tunnel_sessions/{id}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnel_sessions/ts_1a2P6C4wcXpIqs96OzAPbLcUsWY
Response

Returns a 200 response on success

Example Response
{
  "agent_version": "",
  "credential": {
    "id": "cr_1a2P6DUbcBnWDndO7eHTNGxKP1q",
    "uri": "https://api.ngrok.com/credentials/cr_1a2P6DUbcBnWDndO7eHTNGxKP1q"
  },
  "id": "ts_1a2P6C4wcXpIqs96OzAPbLcUsWY",
  "ip": "10.42.0.6",
  "metadata": "",
  "os": "linux",
  "region": "us",
  "started_at": "2020-04-03T16:15:37Z",
  "transport": "ngrok/2",
  "uri": "https://api.ngrok.com/tunnel_sessions/ts_1a2P6C4wcXpIqs96OzAPbLcUsWY"
}
Fields
agent_version version of the ngrok agent that started this ngrok tunnel session
credential reference to the tunnel 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. Either ngrok/v2 or ssh
uri URI to the API resource of the tunnel session

Restart Tunnel 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
GET/tunnel_sessions/{id}/restart
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnel_sessions/foo/restart
Response

Returns a 204 response with no body on success

Stop Tunnel Agent

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

Request
GET/tunnel_sessions/{id}/stop
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnel_sessions/foo/stop
Response

Returns a 204 response with no body on success

Update Tunnel 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
GET/tunnel_sessions/{id}/update
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnel_sessions/foo/update
Response

Returns a 204 response with no body on success

List Tunnels

List all online tunnels currently running on the account.

Request
GET/tunnels
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 1" \
https://api.ngrok.com/tunnels
Response

Returns a 200 response on success

Example Response
{
  "tunnels": [
    {
      "id": "tn_1a2P5wC9QIevs1YZmcXmVEctXN8",
      "public_url": "https://b0223e22.ngrok.io",
      "started_at": "2020-04-03T16:15:35Z",
      "metadata": "",
      "proto": "https",
      "region": "us",
      "tunnel_session": {
        "id": "ts_1a2P5zWhcTDvOahQYAFIQzGtKo6",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_1a2P5zWhcTDvOahQYAFIQzGtKo6"
      }
    },
    {
      "id": "tn_1a2P5vQTV3rFQtyGXTzDWZquZsI",
      "public_url": "http://b0223e22.ngrok.io",
      "started_at": "2020-04-03T16:15:35Z",
      "metadata": "",
      "proto": "http",
      "region": "us",
      "tunnel_session": {
        "id": "ts_1a2P5zWhcTDvOahQYAFIQzGtKo6",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_1a2P5zWhcTDvOahQYAFIQzGtKo6"
      }
    }
  ],
  "uri": "https://api.ngrok.com/tunnels"
}
Fields
tunnels the list of all online tunnels on this account
uri URI of the tunnels list API resource