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
.
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 requestedOrigin
. - 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
inAccess-Control-Allow-Headers
- The API responds with
Access-Control-Allow-Credentials: true
because theAuthorization
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.