Docs for ngrok link

Overview

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 supplment 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 client. Those differences are enumerated here.

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

  • Request inspection for all tunnels is disabled by default.
  • Automatic client updates are disabled by default.
  • The console UI is disabled and ngrok logs to stdout by default.

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.

  • ngrok service start
  • ngrok service stop
  • ngrok service restart
  • ngrok service uninstall

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

Creating new client authtokens is easy. Just go to 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.

The full authtoken you generate will only be displayed 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.

The ngrok.com REST API

ngrok.com exposes a REST API that grants programmatic access to:

  • List all active tunnels connected to your account
  • List all reserved domains for your account

Base URL and Authentication

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

The API credentials to access the ngrok.com REST API are available on your ngrok.com dashboard.

Access the root API resource of a running ngrok client
curl -H "Authorization: Bearer <<TOKEN>>" 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 ngrok.com API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. The mechanism by which a caller opts into a new version of the API will be determined in the future when it becomes necessary. Examples of non-breaking changes to the API that will not be opt-in include the following.

  • The addition of new resources
  • The addition of new methods to existing resources
  • The addition of new fields on existing resource representations
  • Bug fixes which change the API to match documented behavior

List Online Tunnels

Returns a list of all tunnels online for your account

Request
GET/tunnels
Response
Parameters
tunnels list of all online tunnels for this account
Tunnel Object Parameters
id unique tunnel resource identifier
clients list of all clients hosting the tunnel. This list will always have at least one entry.
proto tunnel protocol type
region identifier of region where tunnel is hosted
public_url URL of the tunnel's public endpoint
metadata user-supplied metadata for the connected client. See the metadata configuration option.
started_at ISO-8601 timestamp of when the tunnel was initiated
Client Object Parameters
id UUID of the ngrok client. It is generated each time an ngrok client starts
ip IP address of client hosting the tunnel
version version of the ngrok client
Example Response
{
    "tunnels": [
        {
            "clients": [
                {
                    "id": "c8aeae2f86ddba78b6ef1aae7729bd99",
                    "ip": "28.1.209.31",
                    "version": "2.1.17"
                }
            ],
            "proto": "http",
            "id": "tn_4d64bf1c28140377fe7538bf6ffd8238",
            "public_url": "http://095f807b.ngrok.io",
            "region": "us",
            "metadata": "",
            "started_at": "2015-01-21T02:39:29Z"
        },
        {
            "clients": [
                {
                    "id": "c8aeae2f86ddba78b6ef1aae7729bd99",
                    "ip": "28.1.209.31",
                    "version": "2.1.17"
                }
            ],
            "proto": "https",
            "public_url": "https://095f807b.ngrok.io",
            "region": "us",
            "metadata": "",
            "id": "tn_928949b3ae2783a804d9b7bba1dfdb35",
            "started_at": "2015-01-21T02:39:29Z"
        }
    ],
    "uri": "https://api.ngrok.com/tunnels"
}

List Reserved Domains

Returns a list of all domains reserved for your account

Request
GET/reserved_domains
Response
Parameters
reserved_domains the list of reserved domains for this account
Reserved Domain Object Parameters
domain name of the reserved domain
created_at time of domain reservation as an ISO-8601 timestamp
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
id unique reserved domain resource identifier
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved domain
Example Response
{
    "reserved_domains": [
        {
            "cname_target": null,
            "created_at": "2014-03-02T09:28:35Z",
            "domain": "x.ngrok.io",
            "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
            "region": "us",
            "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
        },
        {
            "cname_target": "m2qgkjdu.cname.us.ngrok.io",
            "created_at": "2014-05-30T17:10:49Z",
            "domain": "app.example.com",
            "id": "rd_82hVw9caM9qHAwAreLhY9",
            "region": "us",
            "uri": "https://api.ngrok.com/reserved_domains/rd_82hVw9caM9qHAwAreLhY9"
        }
    ],
    "uri": "https://api.ngrok.com/reserved_domains"
}

Reserve Domain

Reserves a new domain for your account

Request
POST/reserved_domains
Parameters
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. This field is optional. The default is us. (au, eu, ap, us)
Example Request
curl -H "Authorization: Bearer <TOKEN>" -d "name=app&region=au" https://api.ngrok.com/reserved_domains
Response

Returns a 201 status code on successful reservation of the domain

Parameters
domain name of the reserved domain
created_at time of domain reservation as an ISO-8601 timestamp
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
id unique reserved domain resource identifier
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved domain
Example Response
{
    "cname_target": null,
    "created_at": "2015-01-02T09:28:35Z",
    "domain": "app.au.ngrok.io",
    "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
    "region": "au",
    "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
}

Reserved Domain Detail

Returns detailed information about a reserved domain.

Request
GET/reserved_domains/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response
Parameters
domain name of the reserved domain
created_at time of domain reservation as an ISO-8601 timestamp
cname_target dns CNAME target for a custom hostname, otherwise null if the reserved domain is a subdomain of *.ngrok.io
id unique reserved domain resource identifier
region Identifies the geographic ngrok datacenter where the domain is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved domain
Example Response
{
    "cname_target": null,
    "created_at": "2015-01-02T09:28:35Z",
    "domain": "app.ngrok.io",
    "id": "rd_3MQYYZRQ7cgqmnJ5wqFCu",
    "region": "us",
    "uri": "https://api.ngrok.com/reserved_domains/rd_3MQYYZRQ7cgqmnJ5wqFCu"
}

Release Reserved Domain

Release a reserved domain

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

Returns a 204 response with no body on success

List Reserved Addresses

Returns a list of all TCP addresses reserved for your account

Request
GET/reserved_addrs
Example Request
curl -H "Authorization: Bearer <TOKEN>" https://api.ngrok.com/reserved_addrs
Response
Parameters
reserved_addrs the list of reserved addresses for this account
Reserved Addr Object Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
id unique reserved address resource identifier
region Identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved address
Example Response
{
    "reserved_addrs": [
        {
            "addr": "1.tcp.au.ngrok.io:20003",
            "created_at": "2015-01-02T13:49:21Z",
            "id": "ra_2ABmiPTLgavPn8PYYNMS3",
            "region": "au",
            "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
        },
        {
            "addr": "1.tcp.eu.ngrok.io:20001",
            "created_at": "2015-01-02T13:49:21Z",
            "id": "ra_5mhjYkKVE1LpVW5G3UaAz",
            "region": "eu",
            "uri": "https://api.ngrok.com/reserved_addrs/ra_5mhjYkKVE1LpVW5G3UaAZ"
        }
    ],
    "uri": "https://api.ngrok.com/reserved_addrs"
}

Reserve Address

Reserve a new address for your account

Request
POST/reserved_addrs
Example Request
Parameters
region Reserve the address in this geographic ngrok datacenter. This field is optional. The default is us. (au, eu, ap, us)
curl -H "Authorization: Bearer <TOKEN>" -d "region=us" https://api.ngrok.com/reserved_addrs
Response

Returns a 201 status code on successful reservation of an address

Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
id unique reserved address resource identifier
region Identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved address
Example Response
{
    "addr": "1.tcp.ngrok.io:20003",
    "created_at": "2015-01-02T13:49:21Z",
    "id": "ra_2ABmiPTLgavPn8PYYNMS3",
    "region": "us",
    "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
}

Reserved Address Detail

Returns detailed information about a reserved address.

Request
GET/reserved_addrs/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" https://api.ngrok.com/reserved_addrs/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response
Parameters
addr the reserved TCP address (host:port)
created_at time of address reservation as an ISO-8601 timestamp
id unique reserved address resource identifier
region Identifies the geographic ngrok datacenter where the address is reserved. (au, eu, ap, us)
uri URI to API resource of the reserved address
Example Response
{
    "addr": "1.tcp.ngrok.io:20003",
    "created_at": "2015-01-02T13:49:21Z",
    "id": "ra_2ABmiPTLgavPn8PYYNMS3",
    "region": "us",
    "uri": "https://api.ngrok.com/reserved_addrs/ra_2ABmiPTLgavPn8PYYNMS1"
}

Release Reserved Address

Release a reserved address

Request
DELETE/reserved_addrs/:id
Example Request
curl -H "Authorization: Bearer <TOKEN>" -XDELETE https://api.ngrok.com/reserved_addrs/rd_3MQYYZRQ7cgqmnJ5wqFCu
Response

Returns a 204 response with no body on success

List Credentials

Returns a list of all credentials for your account

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

Create Credential

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

Request
POST/credentials
Parameters
description a human-readable description of who or what will use the credential to authenticate. This field is optional.
acl a list of ACL rules. If no ACL is specified, the credential will have all permissions. The only allowed ACL rule at this time is the bind rule. The bind rule allows you to restrict what domains and addresses the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io.
Example Request
curl -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" -d '{"description":"for device #132", "acl": ["bind:myname.com", "bind:1.tcp.ngrok.io:20001"]}' https://api.ngrok.com/credentials
Response

Returns a 201 status code on successful creation of the credential

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

Credential Detail

Returns detailed information about a tunnel authtoken credential

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

Revoke Credential

Revoke a credential so that it may no longer be used

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

Returns a 204 response with no body on success