ngrok-api#

This is the official helper library for working with the ngrok HTTP API from Python.

Getting Started#

Installation#

pip install ngrok-api

Quickstart Example#

After you’ve installed the package, you’ll need an API key. Create one on the API Keys page of your ngrok dashboard.

In your application’s code, construct an Client object with the API key. API services can be accessed as properties of the client object. That’s it!

import ngrok

# construct the api client
client = ngrok.Client("<API KEY>")

# list all online tunnels
for t in client.tunnels.list():
    print(t)

# create an ip policy the allows traffic from some subnets
policy = client.ip_policies.create()
for cidr in ["24.0.0.0/8", "12.0.0.0/8"]:
    client.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id, action="allow")

Automatic Paging#

The ngrok API pages all list resources but this library abstracts that away from you. All response objects from any list() methods return an object that implements an __iter__() method which will automatically fetch additional pages for you.

import ngrok

client = ngrok.Client("<API KEY>")

# list all ip policies, transparently fetching additional
# pages for you if necessary
for p in client.ip_policies.list():
    print(p)

Instance Methods#

Instance methods like update and delete can be invoked on an instance of an API object itself as well as directly without needing to first fetch the object.

::

import ngrok

client = ngrok.Client(“<API KEY>”)

# update the metadata of a credential cred = client.credentials.get(“cr_1kYyunEyn6XHHlqyMBLrj5nxkoz”) cred.update(metadata=json.dumps({

“server_name”: “giraffe-1”,

}))

# or do it in single call cred = client.credentials.update(“cr_1kYyunEyn6XHHlqyMBLrj5nxkoz”, metadata=json.dumps({

“server_name”: “giraffe-1”,

}))

Error Handling#

The ngrok API returns detailed information when an API call fails. Consult the section on errors for additional details.

import ngrok

client = ngrok.Client("<API KEY>")

try:
    policy = client.ip_policies.create()
    client.ip_policy_rules.create(cidr="24.0.0.0/8", ip_policy_id=policy.id, action="not a valid action")
except ngrok.Error as e:
    print("http status code", e.http_status_code)
    print("ngrok error code", e.error_code)
    print("ngrok error message", e.message)
    print("optional additional error-specific details", e.details)

API Reference#

API

Services