The ngrok API

Overview

The ngrok API provides programmatic access to all of ngrok's resources.

The API is REST-ish. It follows most of the conventions of a REST API but diverges slightly when the REST model does not fit well.

The API is available at https://api.ngrok.com. The API listens only on port 443 to help avoid any accidental unencrypted requests.

The API is designed to be simple enough to be called with curl and HTTP libraries in your programming language of choice. We also publish other ways to interact with the API like native API client libraries, a native CLI and a Terraform Provider.

API Reference Docs

• API Reference: Documentation of all API resources and endpoints. We know it's important, that's why it's first :)

Other ways to interact with the API

• Agent API CLI: Explore and script the API via the ngrok api commands included in the ngrok agent.
• API Client Libraries: We publish idiomatic API client libraries for all major programming languages
• Terraform Provider: Use ngrok's Terraform provider to manage ngrok resources

You may be looking for other programmatic ways to work with ngrok

• Agent API: The ngrok agent has its own API if you're trying to dynamically start and stop endpoints and tunnels
• Agent SDKs: If you're looking to embed ngrok agent functionality as a library in your own software

Quickstart

Start by generating a new API key in the ngrok Dashboard.

Access the API with curl

curl https://api.ngrok.com -H "authorization: Bearer {API Key}" -H "ngrok-version: 2"

Access the API with the agent CLI

ngrok config add-api-key "{API Key}"
ngrok api endpoints list

Client Libraries

We publish open-source API client libraries to make working with the ngrok API feel native and fluent in your favorite programming language. Library repositories are published in the ngrok github organization.

Language	Installation	Documentation	Repository
Go	go get github.com/ngrok/ngrok-api-go/v4	Documentation	GitHub
.NET	dotnet add package NgrokApi	Documentation	GitHub
Ruby	gem install ngrok-api	Documentation	GitHub
Python	pip install ngrok-api	Documentation	GitHub
Java (unstable)	See the README for installing with Maven	Documentation	GitHub
Scala (unstable)	See the README for installing with Maven	Documentation	GitHub

Terraform Provider

When you use ngrok resources as part of production infrastructure, it is an industry best practice to define them using an infrastructure-as-code tool like Terraform. We publish an official Terraform provider that consumes the ngrok API to your resources in this way.

Consult the documentation for the ngrok Terraform provider on Hashicorp's Terraform Registry.

example.tf

# Configure the ngrok provider
provider "ngrok" {
  api_key = "{API_KEY}"
}

# Provision an ngrok domain
resource "ngrok_reserved_domain" "my_domain" {
  name   = "my-domain.example.com"
  region = "us"
  certificate_management_policy {
    authority        = "letsencrypt"
    private_key_type = "ecdsa"
  }
}

Authentication

Base URL	https://api.ngrok.com
Authentication Header	authorization: Bearer {API Key}

Requests to the API must include an API key as a bearer token in the Authorization header.

• API Keys on the ngrok dashboard: Provision your first API key from your ngrok dashboard.
• API keys API Resource: Once you have an API key, you may provision additional API keys programmatically.

Content Types

Requests to the API with a content body must set a content-type header of application/json. All responses returned by the API will use the application/json content type.

Versioning and API Stability

Requests to the API must set the ngrok-version header. The latest version is 2. All other versions are deprecated.

The ngrok API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. The following non-breaking changes to the API may be made to existing versions:

• 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

Pagination

List endpoints can be paginated using the query parameters limit and before_id. Results are returned ordered from newest to oldest. The maximum value of limit is 100. If a limit is not specified, it will default to 100. If before_id is not specified, the first page of results will be returned. You can provide an explicit value for before_id to retrieve items created before the given ID. Each response to a list request will include a next_page_uri field, which will be the full URL you can request to retrieve the next page of results. If there are no more results, next_page_uri will be null.

Timestamps and Timezones

Timestamp fields in the ngrok API are represented as strings that are returned in the RFC 3339 format. Timestamps returned by the API are in UTC time which is indicated by a Z at the end.

Rate Limits

The ngrok API enforces a limit on all accounts of 120 requests over a rolling 60 second window. If you exceed the rate limit, ngrok will return ERR_NGROK_226 and an HTTP Status Code of 429.

IP Restrictions

All API access requires an API key, but you may also further restrict which IPs are permitted to make requests to the API. You may define one or more IP Policies to configure which CIDR blocks may manipulate the API for your account.

If you use SCIM with an IdP, you may need to add the IPs of your IdP as well because SCIM requests to the ngrok API are subject to these IP restrictions as well.

IP Restrictions can be configured manually on the ngrok dashboard or programmatically via API with a type of api.

• IP Restrictions on your ngrok dashboard
• IP Restrictions API Resource

Errors

We believe that it is important to provide a well-defined interface to errors you encounter when working with the ngrok API. Well-defined error surfaces and codes are what allow your software to appropriately handle error conditions.

Errors returned by the ngrok API are serialized with the following example format:

{
  "error_code": "ERR_NGROK_218",
  "status_code": 400,
  "msg": "Your request has not specified an API version. Please include the version you wish to use in the Ngrok-Version header. Supported versions: 2.",
  "details": {
    "operation_id": "op_2RfSBcv0nsy71XCHWOegjx1OoKh"
  }
}

Every error returned by the ngrok API includes a globally unique error code in the error_code property field. This error code is distinct for every possible error condition that can be encountered so your software can properly handle different error conditions.

Consult the Error Reference Documentation for the complete list of all error codes returned by ngrok.

CORS

The ngrok API supports CORS (Cross Origin Resource Sharing) so that you may initiate requests to it from Javascript running in a web browser on other domains.

The response to CORS requests include the Access-Control-Allow-Origin and Access-Control-Allow-Credentials headers.

The ngrok API identifies any request with an OPTIONS method and the headers Origin and Access-Control-Request-Method as a CORS preflight request. The API responds to CORS preflight requests as follows:

• The API sets the Access-Control-Allow-Origin to match the requested Origin.
• The API sets Access-Control-Allow-Methods to all supported methods for the requested resource.
• The API echoes back all requested header from Access-Control-Request-Headers in Access-Control-Allow-Headers
• The API responds with Access-Control-Allow-Credentials: true because the Authorization header is required for accessing API resources.
• The API sets the Access-Control-Max-Age header to enable the preflight response to be cached for up to 10 minutes.

Pricing

The API is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the API incur a cost.

API IP Restrictions is available on the Enterprise plan.