▾ Nav
Don't have an ngrok account?

Sign up for free to get more bandwidth, longer tunnel timeouts, and a lot more.

The ngrok HTTP API

Introduction

The ngrok HTTP API is available at https://api.ngrok.com. It provides programmatic access to all of ngrok's resources.

This documentation reference is most helpful after reading the ngrok documentation. It assumes you are already familiar with the ngrok domain model.

The API is REST-ish. It follows most of the conventions of a REST API but breaks some when the REST model does not fit well. The API listens only on port 443 to help avoid any accidental unencrypted requests.

If you are looking to programmatically start and stop tunnels, instead consult the documentation of the ngrok agent API.

This API is part of our Beta suite of features and any user subscribed to a paid ngrok plan can request access. Please note, we may be charging for some features in our Beta suite once they are generally available.

Authentication

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

API keys to access the ngrok.com HTTP API can be provisioned on the API Keys page of your ngrok dashboard. API keys can also be created via the API keys API Resource. 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 {API_KEY}" -H "ngrok-version: 2" https://api.ngrok.com/

Content Types

All request bodies sent to the API must use a content type of application/json. Ensure that your client sets the request's Content-Type header appropriately. All responses returned by the API will also be returned with an application/json content type.

Versioning and API Stability

The caller must specify a version by sending an ngrok-version header with each request. The latest version is 2. Versions 0 and 1 are supported for some accounts 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. The following non-breaking changes to the API may be made to existing versions without an opt-in:

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.

API Clients

ngrok's HTTP API is designed to be simple enough to be called with curl and the HTTP library in your programming language of choice. We also believe that higher-level interfaces are better fits depending on the type of automation you're building. We publish a number of other official API clients and tools that make automating your ngrok workflows easy.

Client Libraries

ngrok publishes API client libraries to make working with ngrok resources feel native and fluent in your favorite programming language. All of our client libraries are open source and published under the ngrok github organization.

Language Installation Documentation
Go go get github.com/ngrok/ngrok-api-go/v3 Documentation
Python pip install ngrok-api Documentation
.NET dotnet add package NgrokApi Documentation
JavaScript and TypeScript npm i @ngrok/ngrok-api Documentation
Ruby gem install ngrok-api Documentation
Java see docs Documentation
Scala see docs Documentation

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 (IaC) tool like Terraform. We publish an official Terraform provider that consumes the ngrok API to manage ngrok 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"
  }
}

API Resources

Create API Key

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

Request
POST/api_keys
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"ad-hoc dev testing","metadata":"{\"environment\":\"dev\"}"}' \
https://api.ngrok.com/api_keys
Parameters
description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "uri": "https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2021-10-20T12:07:31Z",
  "token": "1zlngJQ0cAEVCWcpxJFkIBPMlLv_cZKq1nm9HDJ69Mp5TPDk"
}
Fields
id string

unique API key resource identifier

uri string

URI to the API resource of this API key

description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

created_at string

timestamp when the api key was created, RFC 3339 format

token string

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: 2" \
https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv
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: 2" \
https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv
Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "uri": "https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2021-10-20T12:07:31Z",
  "token": null
}
Fields
id string

unique API key resource identifier

uri string

URI to the API resource of this API key

description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

created_at string

timestamp when the api key was created, RFC 3339 format

token string

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: 2" \
https://api.ngrok.com/api_keys
Response

Returns a 200 response on success

Example Response
{
  "keys": [
    {
      "id": "ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
      "uri": "https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
      "description": "ad-hoc dev testing",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2021-10-20T12:07:31Z",
      "token": null
    },
    {
      "id": "ak_1zlnfabCEC739BOWHqGFiXLmsWu",
      "uri": "https://api.ngrok.com/api_keys/ak_1zlnfabCEC739BOWHqGFiXLmsWu",
      "description": "api key for example generation",
      "metadata": "",
      "created_at": "2021-10-20T12:07:25Z",
      "token": null
    }
  ],
  "uri": "https://api.ngrok.com/api_keys",
  "next_page_uri": null
}
Fields
keys APIKey

the list of API keys for this account

uri string

URI of the API keys list API resource

next_page_uri string

URI of the next page, or null if there is no next page

APIKey fields
id string

unique API key resource identifier

uri string

URI to the API resource of this API key

description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

created_at string

timestamp when the api key was created, RFC 3339 format

token string

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.

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: 2" \
-d '{"metadata":"{\"environment\":\"dev\", \"owner_id\": 123}"}' \
https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv
Parameters
id string
description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "uri": "https://api.ngrok.com/api_keys/ak_1zlngJQ0cAEVCWcpxJFkIBPMlLv",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2021-10-20T12:07:31Z",
  "token": null
}
Fields
id string

unique API key resource identifier

uri string

URI to the API resource of this API key

description string

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

metadata string

arbitrary user-defined data of this API key. optional, max 4096 bytes

created_at string

timestamp when the api key was created, RFC 3339 format

token string

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: 2" \
-d '{"urls":["http://legit-facebook-login.ngrok.io/login"],"metadata":"{\"incident_id\":1233122}"}' \
https://api.ngrok.com/abuse_reports
Parameters
urls List<string>

a list of URLs containing suspected abusive content

metadata string

arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "abrp_1zlnjUKxX51Xi3c6RQMWk8D5NW8",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1zlnjUKxX51Xi3c6RQMWk8D5NW8",
  "created_at": "2021-10-20T12:07:56Z",
  "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 string

ID of the abuse report

uri string

URI of the abuse report API resource

created_at string

timestamp that the abuse report record was created in RFC 3339 format

urls List<string>

a list of URLs containing suspected abusive content

metadata string

arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.

status string

Indicates whether ngrok has processed the abuse report. one of PENDING, PROCESSED, or PARTIALLY_PROCESSED

hostnames AbuseReportHostname

an array of hostname statuses related to the report

AbuseReportHostname fields
hostname string

the hostname ngrok has parsed out of one of the reported URLs in this abuse report

status string

indicates what action ngrok has taken against the hostname. one of PENDING, BANNED, UNBANNED, or IGNORE

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: 2" \
https://api.ngrok.com/abuse_reports/abrp_1zlnjUKxX51Xi3c6RQMWk8D5NW8
Response

Returns a 200 response on success

Example Response
{
  "id": "abrp_1zlnjUKxX51Xi3c6RQMWk8D5NW8",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1zlnjUKxX51Xi3c6RQMWk8D5NW8",
  "created_at": "2021-10-20T12:07:56Z",
  "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 string

ID of the abuse report

uri string

URI of the abuse report API resource

created_at string

timestamp that the abuse report record was created in RFC 3339 format

urls List<string>

a list of URLs containing suspected abusive content

metadata string

arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.

status string

Indicates whether ngrok has processed the abuse report. one of PENDING, PROCESSED, or PARTIALLY_PROCESSED

hostnames AbuseReportHostname

an array of hostname statuses related to the report

AbuseReportHostname fields
hostname string

the hostname ngrok has parsed out of one of the reported URLs in this abuse report

status string

indicates what action ngrok has taken against the hostname. one of PENDING, BANNED, UNBANNED, or IGNORE

Create Agent Ingress

Create a new Agent Ingress. The ngrok agent can be configured to connect to ngrok via the new set of addresses on the returned Agent Ingress.

Request
POST/agent_ingresses
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme devices","domain":"connect.acme.com"}' \
https://api.ngrok.com/agent_ingresses
Parameters
description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

domain string

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

Response

Returns a 200 response on success

Example Response
{
  "id": "agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "description": "acme devices",
  "metadata": "",
  "domain": "connect.acme.com",
  "ns_targets": [
    "0.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "1.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "2.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "3.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com"
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2021-10-20T12:08:58Z"
}
Fields
id string

unique Agent Ingress resource identifier

uri string

URI to the API resource of this Agent ingress

description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

domain string

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

ns_targets List<string>

a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok

region_domains List<string>

a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions

created_at string

timestamp when the Agent Ingress was created, RFC 3339 format

Delete Agent Ingress

Delete an Agent Ingress by ID

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

Returns a 204 response with no body on success

Get Agent Ingress

Get the details of an Agent Ingress by ID.

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

Returns a 200 response on success

Example Response
{
  "id": "agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "description": "ACME Co. Device Ingress",
  "metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
  "domain": "connect.acme.com",
  "ns_targets": [
    "0.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "1.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "2.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "3.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com"
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2021-10-20T12:08:58Z"
}
Fields
id string

unique Agent Ingress resource identifier

uri string

URI to the API resource of this Agent ingress

description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

domain string

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

ns_targets List<string>

a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok

region_domains List<string>

a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions

created_at string

timestamp when the Agent Ingress was created, RFC 3339 format

List Agent Ingresses

List all Agent Ingresses owned by this account

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

Returns a 200 response on success

Example Response
{
  "ingresses": [
    {
      "id": "agin_1zlnrHlibHAywyAvG5wk0rx5olk",
      "uri": "https://api.ngrok.com/agent_ingresses/agin_1zlnrHlibHAywyAvG5wk0rx5olk",
      "description": "acme devices",
      "metadata": "",
      "domain": "connect.acme.com",
      "ns_targets": [
        "0.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
        "1.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
        "2.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
        "3.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com"
      ],
      "region_domains": [
        "tunnel.us.connect.acme.com"
      ],
      "created_at": "2021-10-20T12:08:58Z"
    }
  ],
  "uri": "https://api.ngrok.com/agent_ingresses",
  "next_page_uri": null
}
Fields
ingresses AgentIngress

the list of Agent Ingresses owned by this account

uri string

URI of the Agent Ingress list API resource

next_page_uri string

URI of the next page, or null if there is no next page

AgentIngress fields
id string

unique Agent Ingress resource identifier

uri string

URI to the API resource of this Agent ingress

description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

domain string

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

ns_targets List<string>

a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok

region_domains List<string>

a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions

created_at string

timestamp when the Agent Ingress was created, RFC 3339 format

Update Agent Ingress

Update attributes of an Agent Ingress by ID.

Request
PATCH/agent_ingresses/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"ACME Co. Device Ingress","metadata":"{\"device_sku\": \"824JS4RZ1F8X\"}"}' \
https://api.ngrok.com/agent_ingresses/agin_1zlnrHlibHAywyAvG5wk0rx5olk
Parameters
id string
description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response
{
  "id": "agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_1zlnrHlibHAywyAvG5wk0rx5olk",
  "description": "ACME Co. Device Ingress",
  "metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
  "domain": "connect.acme.com",
  "ns_targets": [
    "0.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "1.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "2.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com",
    "3.agin_1zlnrHlibHAywyAvG5wk0rx5olk.ns.ngrok.com"
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2021-10-20T12:08:58Z"
}
Fields
id string

unique Agent Ingress resource identifier

uri string

URI to the API resource of this Agent ingress

description string

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

domain string

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

ns_targets List<string>

a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok

region_domains List<string>

a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions

created_at string

timestamp when the Agent Ingress was created, RFC 3339 format

Create Certificate Authority

Upload a new Certificate Authority

Request
POST/certificate_authorities
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"Internal Coprorates Services Authority","metadata":"{\"internal_id\": \"7d2caeee-cdc3-4b26-b2c2-b280b8287552\"}","ca_pem":"-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----"}' \
https://api.ngrok.com/certificate_authorities
Parameters
description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

ca_pem string

raw PEM of the Certificate Authority

Response

Returns a 200 response on success

Example Response
{
  "id": "ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "created_at": "2021-10-20T12:08:34Z",
  "description": "Internal Coprorates Services Authority",
  "metadata": "{\"internal_id\": \"7d2caeee-cdc3-4b26-b2c2-b280b8287552\"}",
  "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----\n",
  "subject_common_name": "Intranet Services Authority",
  "not_before": "2020-05-01T16:27:59Z",
  "not_after": "2021-05-01T16:27:59Z",
  "key_usages": [],
  "extended_key_usages": []
}
Fields
id string

unique identifier for this Certificate Authority

uri string

URI of the Certificate Authority API resource

created_at string

timestamp when the Certificate Authority was created, RFC 3339 format

description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

ca_pem string

raw PEM of the Certificate Authority

subject_common_name string

subject common name of the Certificate Authority

not_before string

timestamp when this Certificate Authority becomes valid, RFC 3339 format

not_after string

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this Certificate Authority can be used for

extended_key_usages List<string>

extended set of actions the private key of this Certificate Authority can be used for

Delete Certificate Authority

Delete a Certificate Authority

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

Returns a 204 response with no body on success

Get Certificate Authority

Get detailed information about a certficate authority

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

Returns a 200 response on success

Example Response
{
  "id": "ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "created_at": "2021-10-20T12:08:34Z",
  "description": "Internal Corporate Services Authority (Legacy)",
  "metadata": "{\"internal_id\": \"7d2caeee-cdc3-4b26-b2c2-b280b8287552\"}",
  "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----\n",
  "subject_common_name": "Intranet Services Authority",
  "not_before": "2020-05-01T16:27:59Z",
  "not_after": "2021-05-01T16:27:59Z",
  "key_usages": [],
  "extended_key_usages": []
}
Fields
id string

unique identifier for this Certificate Authority

uri string

URI of the Certificate Authority API resource

created_at string

timestamp when the Certificate Authority was created, RFC 3339 format

description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

ca_pem string

raw PEM of the Certificate Authority

subject_common_name string

subject common name of the Certificate Authority

not_before string

timestamp when this Certificate Authority becomes valid, RFC 3339 format

not_after string

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this Certificate Authority can be used for

extended_key_usages List<string>

extended set of actions the private key of this Certificate Authority can be used for

List Certificate Authorities

List all Certificate Authority on this account

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

Returns a 200 response on success

Example Response
{
  "certificate_authorities": [
    {
      "id": "ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
      "created_at": "2021-10-20T12:08:34Z",
      "description": "Internal Coprorates Services Authority",
      "metadata": "{\"internal_id\": \"7d2caeee-cdc3-4b26-b2c2-b280b8287552\"}",
      "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----\n",
      "subject_common_name": "Intranet Services Authority",
      "not_before": "2020-05-01T16:27:59Z",
      "not_after": "2021-05-01T16:27:59Z",
      "key_usages": [],
      "extended_key_usages": []
    },
    {
      "id": "ca_1zlnoG0S7dPstxrC5XAnHKRy4h2",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnoG0S7dPstxrC5XAnHKRy4h2",
      "created_at": "2021-10-20T12:08:34Z",
      "description": "Device Connectivity Authority",
      "metadata": "",
      "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEAzCCAuugAwIBAgIUGN+Gv4BdJ17VoVXWrz9j51jcfYowDQYJKoZIhvcNAQEL\nBQAwgZAxCzAJBgNVBAYTAlVTMRMwEQYDVQQIDApDYWxpZm9ybmlhMRYwFAYDVQQH\nDA1TYW4gRnJhbmNpc2NvMRMwEQYDVQQKDApBQ01FLCBJbmMuMR4wHAYDVQQDDBVB\nQ01FIERldmljZSBBdXRob3JpdHkxHzAdBgkqhkiG9w0BCQEWEG9wc0BhY21lLmV4\nYW1wbGUwHhcNMjAwNTAxMTYyNTA5WhcNMjEwNTAxMTYyNTA5WjCBkDELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lz\nY28xEzARBgNVBAoMCkFDTUUsIEluYy4xHjAcBgNVBAMMFUFDTUUgRGV2aWNlIEF1\ndGhvcml0eTEfMB0GCSqGSIb3DQEJARYQb3BzQGFjbWUuZXhhbXBsZTCCASIwDQYJ\nKoZIhvcNAQEBBQADggEPADCCAQoCggEBAO8vxADdMmZANJ0aTAX6Jp50vCjFh2/d\nJLxn4ZAg0fFgkM+Zl+3gxGA7YUUKxIKet6rSeyKAjOX9AFA+idpv5mXnD+0nwPDr\nkwGe1MkYsaWYdMyUEoI9uEodS0LmHItAzV63ovkdagb3fqZqWcJCsoDa22WHt6GN\nT2d4xGD0gEMyDmwxey4XYSy63H1mvQRzhjC5wCzTGOefG76Io0whJka0mr3b6wEv\nSw0YqRF0/BEDlmWU/VWz7YEgWpb0rXaLqQKbZjyFo137X1otZK8vj9MVRWRvYmcF\nHgE+n0ifoCQ/DNVF1mkG6HGK3LREj9LGRBTN683Vqq2W+93B9yuTgr8CAwEAAaNT\nMFEwHQYDVR0OBBYEFLGXXIYFIpkRy4j0VsOdfgxgZpXzMB8GA1UdIwQYMBaAFLGX\nXIYFIpkRy4j0VsOdfgxgZpXzMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQEL\nBQADggEBAFyO7ZWj9w6xzoBWu/XbIVwsQ3kE5k+wrRGyp2rh2v4msAEveCIZP5kT\nCSdr2vr+9HQYiKf1ftsp9tGTLXwrhz3ztC8jIqo4A0grw5B61J0lj+2grKNq1/CK\nxQcpkbnetzo4zsDqFRoN2VK40Ovo4b/IknFa38t06b4t8cYQIqUdkFHMSSIz3Mvx\nRIK6MZlilT8zkWhi9kfCJe/s3cVEAJixNkgO4XNo5VhhxFenyvAL2vDM27dWVtDG\nqL3MFZbcy0/74AJsJDSrflGUQxjrK3WI9PkpKp/xey54XJAbhF63z1VwkJwSwufv\nW9HgidfMN9icgxkScyWpB9KrZHcsLk4=\n-----END CERTIFICATE-----\n",
      "subject_common_name": "ACME Device Authority",
      "not_before": "2020-05-01T16:25:09Z",
      "not_after": "2021-05-01T16:25:09Z",
      "key_usages": [],
      "extended_key_usages": []
    },
    {
      "id": "ca_1zlnlXYRR9mDwxoa4x2uiDczK8X",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnlXYRR9mDwxoa4x2uiDczK8X",
      "created_at": "2021-10-20T12:08:13Z",
      "description": "",
      "metadata": "",
      "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----\n",
      "subject_common_name": "Intranet Services Authority",
      "not_before": "2020-05-01T16:27:59Z",
      "not_after": "2021-05-01T16:27:59Z",
      "key_usages": [],
      "extended_key_usages": []
    }
  ],
  "uri": "https://api.ngrok.com/certificate_authorities",
  "next_page_uri": null
}
Fields
certificate_authorities CertificateAuthority

the list of all certificate authorities on this account

uri string

URI of the certificates authorities list API resource

next_page_uri string

URI of the next page, or null if there is no next page

CertificateAuthority fields
id string

unique identifier for this Certificate Authority

uri string

URI of the Certificate Authority API resource

created_at string

timestamp when the Certificate Authority was created, RFC 3339 format

description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

ca_pem string

raw PEM of the Certificate Authority

subject_common_name string

subject common name of the Certificate Authority

not_before string

timestamp when this Certificate Authority becomes valid, RFC 3339 format

not_after string

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this Certificate Authority can be used for

extended_key_usages List<string>

extended set of actions the private key of this Certificate Authority can be used for

Update Certificate Authority

Update attributes of a Certificate Authority by ID

Request
PATCH/certificate_authorities/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"Internal Corporate Services Authority (Legacy)"}' \
https://api.ngrok.com/certificate_authorities/ca_1zlnoGbF7H87ohLtD91zmzjQKlK
Parameters
id string
description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnoGbF7H87ohLtD91zmzjQKlK",
  "created_at": "2021-10-20T12:08:34Z",
  "description": "Internal Corporate Services Authority (Legacy)",
  "metadata": "{\"internal_id\": \"7d2caeee-cdc3-4b26-b2c2-b280b8287552\"}",
  "ca_pem": "-----BEGIN CERTIFICATE-----\nMIIEETCCAvmgAwIBAgIUU3N6lNzPqar4400cLQMcVHFl+mEwDQYJKoZIhvcNAQEL\nBQAwgZcxCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5l\neTEZMBcGA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQg\nU2VydmljZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9w\nYmVhci5leGFtcGxlMB4XDTIwMDUwMTE2Mjc1OVoXDTIxMDUwMTE2Mjc1OVowgZcx\nCzAJBgNVBAYTAkFVMQwwCgYDVQQIDANOU1cxDzANBgNVBAcMBlN5ZG5leTEZMBcG\nA1UECgwQRHJvcGJlYXIgUHR5IEx0ZDEkMCIGA1UEAwwbSW50cmFuZXQgU2Vydmlj\nZXMgQXV0aG9yaXR5MSgwJgYJKoZIhvcNAQkBFhlzZWN1cml0eUBkcm9wYmVhci5l\neGFtcGxlMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7y/EAN0yZkA0\nnRpMBfomnnS8KMWHb90kvGfhkCDR8WCQz5mX7eDEYDthRQrEgp63qtJ7IoCM5f0A\nUD6J2m/mZecP7SfA8OuTAZ7UyRixpZh0zJQSgj24Sh1LQuYci0DNXrei+R1qBvd+\npmpZwkKygNrbZYe3oY1PZ3jEYPSAQzIObDF7LhdhLLrcfWa9BHOGMLnALNMY558b\nvoijTCEmRrSavdvrAS9LDRipEXT8EQOWZZT9VbPtgSBalvStdoupAptmPIWjXftf\nWi1kry+P0xVFZG9iZwUeAT6fSJ+gJD8M1UXWaQbocYrctESP0sZEFM3rzdWqrZb7\n3cH3K5OCvwIDAQABo1MwUTAdBgNVHQ4EFgQUsZdchgUimRHLiPRWw51+DGBmlfMw\nHwYDVR0jBBgwFoAUsZdchgUimRHLiPRWw51+DGBmlfMwDwYDVR0TAQH/BAUwAwEB\n/zANBgkqhkiG9w0BAQsFAAOCAQEANk25tt8sSfn6Qu1bbhWRbjKgS5z+j9LqyCna\nv3fbSchMthaQR7w0vL69ayroeYdqDZkRMmHjuYKY4NyqyXkkaqVO63wEicCo55d9\npIKuPzc/7xwdRephosjGTQ4QaQ4OnrdpJZieI92m9ODexgsab84AYmwNpbGOI/tK\nnPsQr8x1RfLs2gbBwQ4MYVM3tQQbX0o+yve5nz/NCOq4vdG+eKON5u6VYMkOOg9F\nVyNY1iISQkpNk/AF6Vi9BGuDb5Hg0phEl1Q0ntCO7ZHAUHjy0ucqXZiXoXdXZcs3\n3zKKLUKva59EDBZ5TUucvXh8VemBtNc6hd1mX4Tq7lAreG9pjQ==\n-----END CERTIFICATE-----\n",
  "subject_common_name": "Intranet Services Authority",
  "not_before": "2020-05-01T16:27:59Z",
  "not_after": "2021-05-01T16:27:59Z",
  "key_usages": [],
  "extended_key_usages": []
}
Fields
id string

unique identifier for this Certificate Authority

uri string

URI of the Certificate Authority API resource

created_at string

timestamp when the Certificate Authority was created, RFC 3339 format

description string

human-readable description of this Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

ca_pem string

raw PEM of the Certificate Authority

subject_common_name string

subject common name of the Certificate Authority

not_before string

timestamp when this Certificate Authority becomes valid, RFC 3339 format

not_after string

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this Certificate Authority can be used for

extended_key_usages List<string>

extended set of actions the private key of this Certificate Authority can be used for

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: 2" \
-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_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/circuit_breaker
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

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 boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/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 boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/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: 2" \
-d '{"enabled":false}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/compression
Parameters
enabled boolean

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 boolean

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/compression
Response

Returns a 200 response on success

Example Response
{
  "enabled": false
}
Fields
enabled boolean

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/compression
Response

Returns a 204 response with no body on success

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: 2" \
-d '{"type":"https","description":"app servers","request_headers":{"add":{"x-frontend":"ngrok"},"remove":["cache-control"]}}' \
https://api.ngrok.com/endpoint_configurations
Parameters
type string

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicyMutate

ip policy module configuration or null

mutual_tls EndpointMutualTLSMutate

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLoggingMutate

logging module configuration or null

saml EndpointSAMLMutate

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicyMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policy_ids List<string>

list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLSMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authority_ids List<string>

list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection

EndpointTLSTermination parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider parameters
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLoggingMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_stream_ids List<string>

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAMLMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-10-20T12:07:28Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "add": {
      "x-frontend": "ngrok"
    },
    "remove": [
      "cache-control"
    ]
  },
  "response_headers": null,
  "ip_policy": null,
  "mutual_tls": null,
  "tls_termination": null,
  "webhook_validation": null,
  "oauth": null,
  "logging": null,
  "saml": null,
  "oidc": null,
  "backend": null
}
Fields
id string

unique identifier of this endpoint configuration

type string

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

created_at string

timestamp when the endpoint configuration was created, RFC 3339 format

uri string

URI of the endpoint configuration API resource

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicy

ip policy module configuration or null

mutual_tls EndpointMutualTLS

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLogging

logging module configuration or null

saml EndpointSAML

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicy fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

EndpointMutualTLS fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLogging fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAML fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO
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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO
Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-10-20T12:07:28Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "add": {
      "x-frontend": "ngrok"
    },
    "remove": [
      "cache-control"
    ]
  },
  "response_headers": null,
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ipp_1zlng0sHdB3szH36i4Thp10uhJ9",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1zlng0sHdB3szH36i4Thp10uhJ9"
      }
    ]
  },
  "mutual_tls": null,
  "tls_termination": null,
  "webhook_validation": null,
  "oauth": null,
  "logging": null,
  "saml": null,
  "oidc": null,
  "backend": null
}
Fields
id string

unique identifier of this endpoint configuration

type string

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

created_at string

timestamp when the endpoint configuration was created, RFC 3339 format

uri string

URI of the endpoint configuration API resource

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicy

ip policy module configuration or null

mutual_tls EndpointMutualTLS

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLogging

logging module configuration or null

saml EndpointSAML

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicy fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

EndpointMutualTLS fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLogging fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAML fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

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: 2" \
https://api.ngrok.com/endpoint_configurations
Response

Returns a 200 response on success

Example Response
{
  "endpoint_configurations": [
    {
      "id": "ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
      "type": "https",
      "description": "app servers",
      "metadata": "",
      "created_at": "2021-10-20T12:07:28Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
      "basic_auth": null,
      "circuit_breaker": null,
      "compression": null,
      "request_headers": {
        "enabled": true,
        "add": {
          "x-frontend": "ngrok"
        },
        "remove": [
          "cache-control"
        ]
      },
      "response_headers": null,
      "ip_policy": null,
      "mutual_tls": null,
      "tls_termination": null,
      "webhook_validation": null,
      "oauth": null,
      "logging": null,
      "saml": null,
      "oidc": null,
      "backend": null
    },
    {
      "id": "ec_1zlnfwq3yd7ivz7LsaEOnPKDqmD",
      "type": "https",
      "description": "web servers",
      "metadata": "",
      "created_at": "2021-10-20T12:07:28Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnfwq3yd7ivz7LsaEOnPKDqmD",
      "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,
        "add": {
          "content-security-policy": "script-src 'self'",
          "x-frame-options": "DENY"
        },
        "remove": []
      },
      "ip_policy": null,
      "mutual_tls": null,
      "tls_termination": null,
      "webhook_validation": null,
      "oauth": null,
      "logging": null,
      "saml": null,
      "oidc": null,
      "backend": null
    }
  ],
  "uri": "https://api.ngrok.com/endpoint_configurations",
  "next_page_uri": null
}
Fields
endpoint_configurations EndpointConfiguration

the list of all endpoint configurations on this account

uri string

URI of the endpoint configurations list API resource

next_page_uri string

URI of the next page, or null if there is no next page

EndpointConfiguration fields
id string

unique identifier of this endpoint configuration

type string

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

created_at string

timestamp when the endpoint configuration was created, RFC 3339 format

uri string

URI of the endpoint configuration API resource

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicy

ip policy module configuration or null

mutual_tls EndpointMutualTLS

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLogging

logging module configuration or null

saml EndpointSAML

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicy fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

EndpointMutualTLS fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLogging fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAML fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

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: 2" \
-d '{"ip_policy":{"ip_policy_ids":["ipp_1zlng0sHdB3szH36i4Thp10uhJ9"]}}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO
Parameters
id string

unique identifier of this endpoint configuration

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicyMutate

ip policy module configuration or null

mutual_tls EndpointMutualTLSMutate

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLoggingMutate

logging module configuration or null

saml EndpointSAMLMutate

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicyMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policy_ids List<string>

list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointMutualTLSMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authority_ids List<string>

list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection

EndpointTLSTermination parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider parameters
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLoggingMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_stream_ids List<string>

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAMLMutate parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-10-20T12:07:28Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnfxieCkS5u8YORMGUoqR6FWO",
  "basic_auth": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": {
    "enabled": true,
    "add": {
      "x-frontend": "ngrok"
    },
    "remove": [
      "cache-control"
    ]
  },
  "response_headers": null,
  "ip_policy": {
    "enabled": true,
    "ip_policies": [
      {
        "id": "ipp_1zlng0sHdB3szH36i4Thp10uhJ9",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1zlng0sHdB3szH36i4Thp10uhJ9"
      }
    ]
  },
  "mutual_tls": null,
  "tls_termination": null,
  "webhook_validation": null,
  "oauth": null,
  "logging": null,
  "saml": null,
  "oidc": null,
  "backend": null
}
Fields
id string

unique identifier of this endpoint configuration

type string

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

description string

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 string

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

created_at string

timestamp when the endpoint configuration was created, RFC 3339 format

uri string

URI of the endpoint configuration API resource

circuit_breaker EndpointCircuitBreaker

circuit breaker module configuration or null

compression EndpointCompression

compression module configuration or null

request_headers EndpointRequestHeaders

request headers module configuration or null

response_headers EndpointResponseHeaders

response headers module configuration or null

ip_policy EndpointIPPolicy

ip policy module configuration or null

mutual_tls EndpointMutualTLS

mutual TLS module configuration or null

tls_termination EndpointTLSTermination

TLS termination module configuration or null

webhook_validation EndpointWebhookValidation

webhook validation module configuration or null

oauth EndpointOAuth

oauth module configuration or null

logging EndpointLogging

logging module configuration or null

saml EndpointSAML

saml module configuration or null

oidc EndpointOIDC

oidc module configuration or null

EndpointCircuitBreaker fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

tripped_duration uint32

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

rolling_window uint32

Integer number of seconds in the statistical rolling window that metrics are retained for.

num_buckets uint32

Integer number of buckets into which metrics are retained. Max 128.

volume_threshold uint32

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

error_threshold_percentage float64

Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

EndpointRequestHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointIPPolicy fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

EndpointMutualTLS fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

EndpointWebhookValidation fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointLogging fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

EndpointSAML fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Create Event Destination

Create a new Event Destination. It will not apply to anything until it is associated with an Event Stream, and that Event Stream is associated with an Endpoint Config.

Request
POST/event_destinations
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\":\"dev\"}","description":"kinesis dev stream","format":"json","target":{"kinesis":{"auth":{"role":{"role_arn":"arn:aws:iam::123456789012:role/example"}},"stream_arn":"arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream2"}}}' \
https://api.ngrok.com/event_destinations
Parameters
metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

EventTarget parameters
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth parameters
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole parameters
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials parameters
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Response

Returns a 200 response on success

Example Response
{
  "id": "ed_1zlnozkhufIP6DBMDrO8v3oCNlw",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2021-10-20T12:08:40Z",
  "description": "kinesis dev stream",
  "format": "json",
  "target": {
    "firehose": null,
    "kinesis": {
      "auth": {
        "role": {
          "role_arn": "arn:aws:iam::123456789012:role/example"
        },
        "creds": null
      },
      "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream2"
    },
    "cloudwatch_logs": null
  },
  "uri": "https://api.ngrok.com/event_destinations/ed_1zlnozkhufIP6DBMDrO8v3oCNlw"
}
Fields
id string

Unique identifier for this Event Destination.

metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

created_at string

Timestamp when the Event Destination was created, RFC 3339 format.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

uri string

URI of the Event Destination API resource.

EventTarget fields
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials fields
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Delete Event Destination

Delete an Event Destination. If the Event Destination is still referenced by an Event Stream, this will throw an error until that Event Stream has removed that reference.

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

Returns a 204 response with no body on success

Get Event Destination

Get detailed information about an Event Destination by ID.

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

Returns a 200 response on success

Example Response
{
  "id": "ed_1zlnozkhufIP6DBMDrO8v3oCNlw",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2021-10-20T12:08:40Z",
  "description": "kinesis dev stream 1 of 3",
  "format": "json",
  "target": {
    "firehose": null,
    "kinesis": {
      "auth": {
        "role": {
          "role_arn": "arn:aws:iam::123456789012:role/example"
        },
        "creds": null
      },
      "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream2"
    },
    "cloudwatch_logs": null
  },
  "uri": "https://api.ngrok.com/event_destinations/ed_1zlnozkhufIP6DBMDrO8v3oCNlw"
}
Fields
id string

Unique identifier for this Event Destination.

metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

created_at string

Timestamp when the Event Destination was created, RFC 3339 format.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

uri string

URI of the Event Destination API resource.

EventTarget fields
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials fields
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

List Event Destinations

List all Event Destinations on this account.

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

Returns a 200 response on success

Example Response
{
  "event_destinations": [
    {
      "id": "ed_1zlnozkhufIP6DBMDrO8v3oCNlw",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2021-10-20T12:08:40Z",
      "description": "kinesis dev stream",
      "format": "json",
      "target": {
        "firehose": null,
        "kinesis": {
          "auth": {
            "role": {
              "role_arn": "arn:aws:iam::123456789012:role/example"
            },
            "creds": null
          },
          "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream2"
        },
        "cloudwatch_logs": null
      },
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnozkhufIP6DBMDrO8v3oCNlw"
    },
    {
      "id": "ed_1zlnoeBShRNjFA7KHZxHRWRjHOn",
      "metadata": "",
      "created_at": "2021-10-20T12:08:37Z",
      "description": "",
      "format": "json",
      "target": {
        "firehose": null,
        "kinesis": {
          "auth": {
            "role": {
              "role_arn": "arn:aws:iam::123456789012:role/example"
            },
            "creds": null
          },
          "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream1"
        },
        "cloudwatch_logs": null
      },
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"
    },
    {
      "id": "ed_1zlnmgYKKF7M0bLDm2sImsKRDv8",
      "metadata": "",
      "created_at": "2021-10-20T12:08:22Z",
      "description": "",
      "format": "json",
      "target": {
        "firehose": null,
        "kinesis": {
          "auth": {
            "role": null,
            "creds": {
              "aws_access_key_id": "AKIAIOSFODNN7EXAMPLE",
              "aws_secret_access_key": null
            }
          },
          "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream"
        },
        "cloudwatch_logs": null
      },
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnmgYKKF7M0bLDm2sImsKRDv8"
    }
  ],
  "uri": "https://api.ngrok.com/event_destinations",
  "next_page_uri": null
}
Fields
event_destinations EventDestination

The list of all Event Destinations on this account.

uri string

URI of the Event Destinations list API resource.

next_page_uri string

URI of the next page, or null if there is no next page.

EventDestination fields
id string

Unique identifier for this Event Destination.

metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

created_at string

Timestamp when the Event Destination was created, RFC 3339 format.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

uri string

URI of the Event Destination API resource.

EventTarget fields
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials fields
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Update Event Destination

Update attributes of an Event Destination.

Request
PATCH/event_destinations/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\":\"dev\", \"stream\":1}","description":"kinesis dev stream 1 of 3"}' \
https://api.ngrok.com/event_destinations/ed_1zlnozkhufIP6DBMDrO8v3oCNlw
Parameters
id string

Unique identifier for this Event Destination.

metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

EventTarget parameters
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth parameters
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole parameters
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials parameters
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs parameters
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Response

Returns a 200 response on success

Example Response
{
  "id": "ed_1zlnozkhufIP6DBMDrO8v3oCNlw",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2021-10-20T12:08:40Z",
  "description": "kinesis dev stream 1 of 3",
  "format": "json",
  "target": {
    "firehose": null,
    "kinesis": {
      "auth": {
        "role": {
          "role_arn": "arn:aws:iam::123456789012:role/example"
        },
        "creds": null
      },
      "stream_arn": "arn:ngrok-local:kinesis:us-east-2:123456789012:stream/mystream2"
    },
    "cloudwatch_logs": null
  },
  "uri": "https://api.ngrok.com/event_destinations/ed_1zlnozkhufIP6DBMDrO8v3oCNlw"
}
Fields
id string

Unique identifier for this Event Destination.

metadata string

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

created_at string

Timestamp when the Event Destination was created, RFC 3339 format.

description string

Human-readable description of the Event Destination. Optional, max 255 bytes.

format string

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

target EventTarget

An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.

uri string

URI of the Event Destination API resource.

EventTarget fields
firehose EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

kinesis EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

cloudwatch_logs EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

delivery_stream_arn string

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields
role AWSRole

A role for ngrok to assume on your behalf to deposit events into your AWS account.

creds AWSCredentials

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields
role_arn string

An ARN that specifies the role that ngrok should use to deliver to the configured target.

AWSCredentials fields
aws_access_key_id string

The ID portion of an AWS access key.

aws_secret_access_key string

The secret portion of an AWS access key.

EventTargetKinesis fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

stream_arn string

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields
auth AWSAuth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

log_group_arn string

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Create Event Source

Add an additional type for which this event subscription will trigger

Request
POST/event_subscriptions/{subscription_id}/sources
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"type":"ip_policy_updated.v0"}' \
https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources
Parameters
subscription_id string

The unique identifier for the Event Subscription that this Event Source is attached to.

type string

Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response
{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0"
}
Fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Delete Event Source

Remove a type for which this event subscription will trigger

Request
DELETE/event_subscriptions/{subscription_id}/sources/{type}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0
Response

Returns a 204 response with no body on success

Get Event Source

Get the details for a given type that triggers for the given event subscription

Request
GET/event_subscriptions/{subscription_id}/sources/{type}
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0
Response

Returns a 200 response on success

Example Response
{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0"
}
Fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

List Event Sources

List the types for which this event subscription will trigger

Request
GET/event_subscriptions/{subscription_id}/sources
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources
Response

Returns a 200 response on success

Example Response
{
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_created.v0"
    },
    {
      "type": "ip_policy_updated.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0"
    }
  ],
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources"
}
Fields
sources EventSource

The list of all Event Sources for an Event Subscription

uri string

URI of the next page, or null if there is no next page.

EventSource fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Update Event Source

Update the type for which this event subscription will trigger

Request
PATCH/event_subscriptions/{subscription_id}/sources/{type}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0
Parameters
subscription_id string

The unique identifier for the Event Subscription that this Event Source is attached to.

type string

Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response
{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpl4rFeGOitd5NxzUBJrPR1B/sources/ip_policy_updated.v0"
}
Fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Create Event Stream

Create a new Event Stream. It will not apply to anything until you associate it with one or more Endpoint Configs.

Request
POST/event_streams
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"staging\"}","description":"low sampling, basic HTTP logs","fields":["http.request.method","http.response.status_code","conn.client_ip"],"event_type":"http_request_complete","destination_ids":["ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"],"sampling_rate":0.1}' \
https://api.ngrok.com/event_streams
Parameters
metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

event_type string

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

Response

Returns a 200 response on success

Example Response
{
  "id": "es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "uri": "https://api.ngrok.com/event_streams/es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "created_at": "2021-10-20T12:08:37Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "low sampling, basic HTTP logs",
  "fields": [
    "http.request.method",
    "http.response.status_code",
    "conn.client_ip"
  ],
  "event_type": "http_request_complete",
  "destination_ids": [
    "ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"
  ],
  "sampling_rate": 0.1
}
Fields
id string

Unique identifier for this Event Stream.

uri string

URI of the Event Stream API resource.

created_at string

Timestamp when the Event Stream was created, RFC 3339 format.

metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

event_type string

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

Delete Event Stream

Delete an Event Stream. Associated Event Destinations will be preserved.

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

Returns a 204 response with no body on success

Get Event Stream

Get detailed information about an Event Stream by ID.

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

Returns a 200 response on success

Example Response
{
  "id": "es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "uri": "https://api.ngrok.com/event_streams/es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "created_at": "2021-10-20T12:08:37Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "medium sampling, basic HTTP logs",
  "fields": [
    "http.request.method",
    "http.response.status_code",
    "conn.client_ip"
  ],
  "event_type": "http_request_complete",
  "destination_ids": [
    "ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"
  ],
  "sampling_rate": 0.3
}
Fields
id string

Unique identifier for this Event Stream.

uri string

URI of the Event Stream API resource.

created_at string

Timestamp when the Event Stream was created, RFC 3339 format.

metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

event_type string

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

List Event Streams

List all Event Streams available on this account.

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

Returns a 200 response on success

Example Response
{
  "event_streams": [
    {
      "id": "es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
      "created_at": "2021-10-20T12:08:37Z",
      "metadata": "{\"environment\": \"staging\"}",
      "description": "low sampling, basic HTTP logs",
      "fields": [
        "http.request.method",
        "http.response.status_code",
        "conn.client_ip"
      ],
      "event_type": "http_request_complete",
      "destination_ids": [
        "ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"
      ],
      "sampling_rate": 0.1
    },
    {
      "id": "es_1zlnmjdLpibhoVRuHFKl2kUwcJT",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmjdLpibhoVRuHFKl2kUwcJT",
      "created_at": "2021-10-20T12:08:22Z",
      "metadata": "",
      "description": "",
      "fields": [
        "http.request.method",
        "http.response.status_code",
        "conn.client_ip"
      ],
      "event_type": "http_request_complete",
      "destination_ids": [
        "ed_1zlnmgYKKF7M0bLDm2sImsKRDv8"
      ],
      "sampling_rate": 0.1
    },
    {
      "id": "es_1zlnmiowSrIvfS0IaxAI69ApR3K",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmiowSrIvfS0IaxAI69ApR3K",
      "created_at": "2021-10-20T12:08:22Z",
      "metadata": "",
      "description": "",
      "fields": [
        "http.request.method",
        "http.response.status_code",
        "conn.client_ip"
      ],
      "event_type": "http_request_complete",
      "destination_ids": [
        "ed_1zlnmgYKKF7M0bLDm2sImsKRDv8"
      ],
      "sampling_rate": 0.1
    }
  ],
  "uri": "https://api.ngrok.com/event_streams",
  "next_page_uri": null
}
Fields
event_streams EventStream

The list of all Event Streams on this account.

uri string

URI of the Event Stream list API resource.

next_page_uri string

URI of the next page, or null if there is no next page.

EventStream fields
id string

Unique identifier for this Event Stream.

uri string

URI of the Event Stream API resource.

created_at string

Timestamp when the Event Stream was created, RFC 3339 format.

metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

event_type string

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

Update Event Stream

Update attributes of an Event Stream by ID.

Request
PATCH/event_streams/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"medium sampling, basic HTTP logs","sampling_rate":0.3}' \
https://api.ngrok.com/event_streams/es_1zlnoYEfv2rFtnWTItzoDnOAQ78
Parameters
id string

Unique identifier for this Event Stream.

metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

Response

Returns a 200 response on success

Example Response
{
  "id": "es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "uri": "https://api.ngrok.com/event_streams/es_1zlnoYEfv2rFtnWTItzoDnOAQ78",
  "created_at": "2021-10-20T12:08:37Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "medium sampling, basic HTTP logs",
  "fields": [
    "http.request.method",
    "http.response.status_code",
    "conn.client_ip"
  ],
  "event_type": "http_request_complete",
  "destination_ids": [
    "ed_1zlnoeBShRNjFA7KHZxHRWRjHOn"
  ],
  "sampling_rate": 0.3
}
Fields
id string

Unique identifier for this Event Stream.

uri string

URI of the Event Stream API resource.

created_at string

Timestamp when the Event Stream was created, RFC 3339 format.

metadata string

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

description string

Human-readable description of the Event Stream. Optional, max 255 bytes.

fields List<string>

A list of protocol-specific fields you want to collect on each event.

event_type string

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

sampling_rate float64

The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.

Create Event Subscription

Create an Event Subscription.

Request
POST/event_subscriptions
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"staging\"}","description":"ip policy creations","sources":[{"type":"ip_policy_created.v0"}],"destination_ids":["ed_1zlnpIT9ctuSrN8HTCuldTslkgq"]}' \
https://api.ngrok.com/event_subscriptions
Parameters
metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSourceReplace

Sources containing the types for which this event subscription will trigger

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

EventSourceReplace parameters
type string

Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response
{
  "id": "esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "created_at": "2021-10-20T12:08:43Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "ip policy creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_1zlnpIT9ctuSrN8HTCuldTslkgq",
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnpIT9ctuSrN8HTCuldTslkgq"
    }
  ]
}
Fields
id string

Unique identifier for this Event Subscription.

uri string

URI of the Event Subscription API resource.

created_at string

When the Event Subscription was created (RFC 3339 format).

metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSource

Sources containing the types for which this event subscription will trigger

destinations Ref

Destinations to which these events will be sent

EventSource fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete Event Subscription

Delete an Event Subscription.

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

Returns a 204 response with no body on success

Get Event Subscription

Get an Event Subscription by ID.

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

Returns a 200 response on success

Example Response
{
  "id": "esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "created_at": "2021-10-20T12:08:43Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "IP Policy Creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_1zlnpIT9ctuSrN8HTCuldTslkgq",
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnpIT9ctuSrN8HTCuldTslkgq"
    }
  ]
}
Fields
id string

Unique identifier for this Event Subscription.

uri string

URI of the Event Subscription API resource.

created_at string

When the Event Subscription was created (RFC 3339 format).

metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSource

Sources containing the types for which this event subscription will trigger

destinations Ref

Destinations to which these events will be sent

EventSource fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

List Event Subscriptions

List this Account’s Event Subscriptions.

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

Returns a 200 response on success

Example Response
{
  "event_subscriptions": [
    {
      "id": "esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
      "created_at": "2021-10-20T12:08:43Z",
      "metadata": "{\"environment\": \"staging\"}",
      "description": "ip policy creations",
      "sources": [
        {
          "type": "ip_policy_created.v0",
          "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV/sources/ip_policy_created.v0"
        }
      ],
      "destinations": [
        {
          "id": "ed_1zlnpIT9ctuSrN8HTCuldTslkgq",
          "uri": "https://api.ngrok.com/event_destinations/ed_1zlnpIT9ctuSrN8HTCuldTslkgq"
        }
      ]
    }
  ],
  "uri": "https://api.ngrok.com/event_subscriptions",
  "next_page_uri": null
}
Fields
event_subscriptions EventSubscription

The list of all Event Subscriptions on this account.

uri string

URI of the Event Subscriptions list API resource.

next_page_uri string

URI of next page, or null if there is no next page.

EventSubscription fields
id string

Unique identifier for this Event Subscription.

uri string

URI of the Event Subscription API resource.

created_at string

When the Event Subscription was created (RFC 3339 format).

metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSource

Sources containing the types for which this event subscription will trigger

destinations Ref

Destinations to which these events will be sent

EventSource fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Update Event Subscription

Update an Event Subscription.

Request
PATCH/event_subscriptions/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"IP Policy Creations"}' \
https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV
Parameters
id string

Unique identifier for this Event Subscription.

metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSourceReplace

Sources containing the types for which this event subscription will trigger

destination_ids List<string>

A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.

EventSourceReplace parameters
type string

Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response
{
  "id": "esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV",
  "created_at": "2021-10-20T12:08:43Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "IP Policy Creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_1zlnpNHhjrarZXrwqcFhH3dQGPV/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_1zlnpIT9ctuSrN8HTCuldTslkgq",
      "uri": "https://api.ngrok.com/event_destinations/ed_1zlnpIT9ctuSrN8HTCuldTslkgq"
    }
  ]
}
Fields
id string

Unique identifier for this Event Subscription.

uri string

URI of the Event Subscription API resource.

created_at string

When the Event Subscription was created (RFC 3339 format).

metadata string

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

description string

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

sources EventSource

Sources containing the types for which this event subscription will trigger

destinations Ref

Destinations to which these events will be sent

EventSource fields
type string

Type of event for which an event subscription will trigger

uri string

URI of the Event Source API resource.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
-d '{"description":"API Outbound Gateway","action":"allow"}' \
https://api.ngrok.com/ip_policies
Parameters
description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

action string

the IP policy action. Supported values are allow or deny

Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "created_at": "2021-10-20T12:07:25Z",
  "description": "API Outbound Gateway",
  "metadata": "",
  "action": "allow"
}
Fields
id string

unique identifier for this IP policy

uri string

URI of the IP Policy API resource

created_at string

timestamp when the IP policy was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

action string

the IP policy action. Supported values are allow or deny

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: 2" \
https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC
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: 2" \
https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC
Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "created_at": "2021-10-20T12:07:25Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}",
  "action": "allow"
}
Fields
id string

unique identifier for this IP policy

uri string

URI of the IP Policy API resource

created_at string

timestamp when the IP policy was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

action string

the IP policy action. Supported values are allow or deny

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: 2" \
https://api.ngrok.com/ip_policies
Response

Returns a 200 response on success

Example Response
{
  "ip_policies": [
    {
      "id": "ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
      "created_at": "2021-10-20T12:07:25Z",
      "description": "API Outbound Gateway",
      "metadata": "",
      "action": "allow"
    },
    {
      "id": "ipp_1zlnfbh8g2g3JaTVIiD6zHMIkJM",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnfbh8g2g3JaTVIiD6zHMIkJM",
      "created_at": "2021-10-20T12:07:25Z",
      "description": "Developer Environments",
      "metadata": "",
      "action": "allow"
    }
  ],
  "uri": "https://api.ngrok.com/ip_policies",
  "next_page_uri": null
}
Fields
ip_policies IPPolicy

the list of all IP policies on this account

uri string

URI of the IP policy list API resource

next_page_uri string

URI of the next page, or null if there is no next page

IPPolicy fields
id string

unique identifier for this IP policy

uri string

URI of the IP Policy API resource

created_at string

timestamp when the IP policy was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

action string

the IP policy action. Supported values are allow or deny

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: 2" \
-d '{"metadata":"metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}"}' \
https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC
Parameters
id string
description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

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_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnfZBgIqSbwLGvQBKy5NnPUpC",
  "created_at": "2021-10-20T12:07:25Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}",
  "action": "allow"
}
Fields
id string

unique identifier for this IP policy

uri string

URI of the IP Policy API resource

created_at string

timestamp when the IP policy was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

action string

the IP policy action. Supported values are allow or deny

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: 2" \
-d '{"ip_policy_ids":["ipp_1zlnlOLcD1b3lEcbZ24N5R5UQEx"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/ip_policy
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policy_ids List<string>

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_1zlnlOLcD1b3lEcbZ24N5R5UQEx",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnlOLcD1b3lEcbZ24N5R5UQEx"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Get IP Policy Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_1zlnlOLcD1b3lEcbZ24N5R5UQEx",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnlOLcD1b3lEcbZ24N5R5UQEx"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

ip_policies Ref
Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete IP Policy Module

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

Returns a 204 response with no body on success

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: 2" \
-d '{"description":"nyc office","cidr":"212.3.14.0/24","ip_policy_id":"ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"}' \
https://api.ngrok.com/ip_policy_rules
Parameters
description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

ip_policy_id string

ID of the IP policy this IP policy rule will be attached to

Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "created_at": "2021-10-20T12:08:00Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
  }
}
Fields
id string

unique identifier for this IP policy rule

uri string

URI of the IP policy rule API resource

created_at string

timestamp when the IP policy rule was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

ip_policy Ref

object describing the IP policy this IP Policy Rule belongs to

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9
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: 2" \
https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9
Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "created_at": "2021-10-20T12:08:00Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
  }
}
Fields
id string

unique identifier for this IP policy rule

uri string

URI of the IP policy rule API resource

created_at string

timestamp when the IP policy rule was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

ip_policy Ref

object describing the IP policy this IP Policy Rule belongs to

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
https://api.ngrok.com/ip_policy_rules
Response

Returns a 200 response on success

Example Response
{
  "ip_policy_rules": [
    {
      "id": "ipr_1zlnk12aXgYmEvI0ZJ1n75KFfjo",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnk12aXgYmEvI0ZJ1n75KFfjo",
      "created_at": "2021-10-20T12:08:00Z",
      "description": "sf office",
      "metadata": "",
      "cidr": "132.2.19.0/24",
      "ip_policy": {
        "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
      }
    },
    {
      "id": "ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
      "created_at": "2021-10-20T12:08:00Z",
      "description": "nyc office",
      "metadata": "",
      "cidr": "212.3.14.0/24",
      "ip_policy": {
        "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
      }
    },
    {
      "id": "ipr_1zlnjuWNKlhP8GEQYYmR6zU8DjA",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnjuWNKlhP8GEQYYmR6zU8DjA",
      "created_at": "2021-10-20T12:08:00Z",
      "description": "alan laptop",
      "metadata": "",
      "cidr": "2.2.2.2/32",
      "ip_policy": {
        "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
      }
    }
  ],
  "uri": "https://api.ngrok.com/ip_policy_rules",
  "next_page_uri": null
}
Fields
ip_policy_rules IPPolicyRule

the list of all IP policy rules on this account

uri string

URI of the IP policy rule list API resource

next_page_uri string

URI of the next page, or null if there is no next page

IPPolicyRule fields
id string

unique identifier for this IP policy rule

uri string

URI of the IP policy rule API resource

created_at string

timestamp when the IP policy rule was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

ip_policy Ref

object describing the IP policy this IP Policy Rule belongs to

Ref fields
id string

a resource identifier

uri string

a uri for locating a 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: 2" \
-d '{"cidr":"212.3.15.0/24"}' \
https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9
Parameters
id string
description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

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_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1zlnjwkPwznJO5GkD2zZb4J9eP9",
  "created_at": "2021-10-20T12:08:00Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnjy8iSTZM3wFMsYbRpRwmdrB"
  }
}
Fields
id string

unique identifier for this IP policy rule

uri string

URI of the IP policy rule API resource

created_at string

timestamp when the IP policy rule was created, RFC 3339 format

description string

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

cidr string

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

ip_policy Ref

object describing the IP policy this IP Policy Rule belongs to

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
-d '{"type":"dashboard","ip_policy_ids":["ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD"]}' \
https://api.ngrok.com/ip_restrictions
Parameters
description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

type string

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

ip_policy_ids List<string>

the set of IP policy identifiers that are used to enforce the restriction

Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "created_at": "2021-10-20T12:08:28Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD"
    }
  ]
}
Fields
id string

unique identifier for this IP restriction

uri string

URI of the IP restriction API resource

created_at string

timestamp when the IP restriction was created, RFC 3339 format

description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

type string

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

ip_policies Ref

the set of IP policies that are used to enforce the restriction

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete IP Restriction

Delete an IP restriction

Request
DELETE/ip_restrictions/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9
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: 2" \
https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9
Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "created_at": "2021-10-20T12:08:28Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD"
    },
    {
      "id": "ipp_1zlnnUsEE2liiLeOtxHQUBjPvmp",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnUsEE2liiLeOtxHQUBjPvmp"
    }
  ]
}
Fields
id string

unique identifier for this IP restriction

uri string

URI of the IP restriction API resource

created_at string

timestamp when the IP restriction was created, RFC 3339 format

description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

type string

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

ip_policies Ref

the set of IP policies that are used to enforce the restriction

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
https://api.ngrok.com/ip_restrictions
Response

Returns a 200 response on success

Example Response
{
  "ip_restrictions": [
    {
      "id": "ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
      "uri": "https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
      "created_at": "2021-10-20T12:08:28Z",
      "description": "",
      "metadata": "",
      "enforced": false,
      "type": "dashboard",
      "ip_policies": [
        {
          "id": "ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD",
          "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD"
        }
      ]
    }
  ],
  "uri": "https://api.ngrok.com/ip_restrictions",
  "next_page_uri": null
}
Fields
ip_restrictions IPRestriction

the list of all IP restrictions on this account

uri string

URI of the IP resrtrictions list API resource

next_page_uri string

URI of the next page, or null if there is no next page

IPRestriction fields
id string

unique identifier for this IP restriction

uri string

URI of the IP restriction API resource

created_at string

timestamp when the IP restriction was created, RFC 3339 format

description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

type string

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

ip_policies Ref

the set of IP policies that are used to enforce the restriction

Ref fields
id string

a resource identifier

uri string

a uri for locating a 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: 2" \
-d '{"ip_policy_ids":["ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD","ipp_1zlnnUsEE2liiLeOtxHQUBjPvmp"]}' \
https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9
Parameters
id string
description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

ip_policy_ids List<string>

the set of IP policy identifiers that are used to enforce the restriction

Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1zlnnUpsMjrvZGnH6zBF7aAxuK9",
  "created_at": "2021-10-20T12:08:28Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnSTOj08t7gQdUlLi1bQPwhD"
    },
    {
      "id": "ipp_1zlnnUsEE2liiLeOtxHQUBjPvmp",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1zlnnUsEE2liiLeOtxHQUBjPvmp"
    }
  ]
}
Fields
id string

unique identifier for this IP restriction

uri string

URI of the IP restriction API resource

created_at string

timestamp when the IP restriction was created, RFC 3339 format

description string

human-readable description of this IP restriction. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

enforced boolean

true if the IP restriction will be enforced. if false, only warnings will be issued

type string

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

ip_policies Ref

the set of IP policies that are used to enforce the restriction

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Replace Logging Module

Request
PUT/endpoint_configurations/{id}/logging
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"event_stream_ids":["es_1zlnmjdLpibhoVRuHFKl2kUwcJT","es_1zlnmiowSrIvfS0IaxAI69ApR3K"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/logging
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_stream_ids List<string>

list of all EventStreams that will be used to configure and export this endpoint’s logs

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "event_streams": [
    {
      "id": "es_1zlnmjdLpibhoVRuHFKl2kUwcJT",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmjdLpibhoVRuHFKl2kUwcJT"
    },
    {
      "id": "es_1zlnmiowSrIvfS0IaxAI69ApR3K",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmiowSrIvfS0IaxAI69ApR3K"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Get Logging Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "event_streams": [
    {
      "id": "es_1zlnmjdLpibhoVRuHFKl2kUwcJT",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmjdLpibhoVRuHFKl2kUwcJT"
    },
    {
      "id": "es_1zlnmiowSrIvfS0IaxAI69ApR3K",
      "uri": "https://api.ngrok.com/event_streams/es_1zlnmiowSrIvfS0IaxAI69ApR3K"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

event_streams Ref

list of all EventStreams that will be used to configure and export this endpoint’s logs

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete Logging Module

Request
DELETE/endpoint_configurations/{id}/logging
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/logging
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: 2" \
-d '{"enabled":true,"certificate_authority_ids":["ca_1zlnlXYRR9mDwxoa4x2uiDczK8X"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/mutual_tls
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authority_ids List<string>

list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_1zlnlXYRR9mDwxoa4x2uiDczK8X",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnlXYRR9mDwxoa4x2uiDczK8X"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Get Mutual TLS Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_1zlnlXYRR9mDwxoa4x2uiDczK8X",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1zlnlXYRR9mDwxoa4x2uiDczK8X"
    }
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

certificate_authorities Ref

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete Mutual TLS Module

Request
DELETE/endpoint_configurations/{id}/mutual_tls
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/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: 2" \
-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_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/oauth
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider parameters
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

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": []
    }
  },
  "options_passthrough": true,
  "cookie_prefix": "ngrok.",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "auth_check_interval": 0
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Get OAuth Module

Request
GET/endpoint_configurations/{id}/oauth
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/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": []
    }
  },
  "options_passthrough": true,
  "cookie_prefix": "ngrok.",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "auth_check_interval": 0
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider EndpointOAuthProvider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

auth_check_interval uint32

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.

EndpointOAuthProvider fields
github EndpointOAuthGitHub

configuration for using github as the identity provider

facebook EndpointOAuthFacebook

configuration for using facebook as the identity provider

microsoft EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

google EndpointOAuthGoogle

configuration for using google as the identity provider

EndpointOAuthGitHub fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

teams List<string>

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

organizations List<string>

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

EndpointOAuthFacebook fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields
client_id string

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

client_secret string

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

scopes List<string>

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

email_addresses List<string>

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

email_domains List<string>

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Delete OAuth Module

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

Returns a 204 response with no body on success

Replace OIDC Module

Request
PUT/endpoint_configurations/{id}/oidc
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"issuer":"https://accounts.google.com","client_id":"some-client-id","client_secret":"some-client-secret","scopes":["profile"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/oidc
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "options_passthrough": false,
  "cookie_prefix": "",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "issuer": "https://accounts.google.com",
  "client_id": "some-client-id",
  "client_secret": "some-client-secret",
  "scopes": [
    "profile"
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Get OIDC Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "options_passthrough": false,
  "cookie_prefix": "",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "issuer": "https://accounts.google.com",
  "client_id": "some-client-id",
  "client_secret": "some-client-secret",
  "scopes": [
    "profile"
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

issuer string

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

client_id string

The OIDC app’s client ID and OIDC audience.

client_secret string

The OIDC app’s client secret.

scopes List<string>

The set of scopes to request from the OIDC identity provider.

Delete OIDC Module

Request
DELETE/endpoint_configurations/{id}/oidc
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/oidc
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: 2" \
-d '{"add":{"X-Baz":"qux","X-Foo":"bar"},"remove":["X-Internal-Header"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/request_headers
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "add": {
    "x-baz": "qux",
    "x-foo": "bar"
  },
  "remove": [
    "x-internal-header"
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from 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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/request_headers
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "add": {
    "x-baz": "qux",
    "x-foo": "bar"
  },
  "remove": [
    "x-internal-header"
  ]
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

remove List<string>

a list of header names that will be removed from 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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/request_headers
Response

Returns a 204 response with no body on success

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: 2" \
-d '{"description":"SSH for device #001","region":"us"}' \
https://api.ngrok.com/reserved_addrs
Parameters
description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

region string

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

endpoint_configuration_id string

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_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "created_at": "2021-10-20T12:07:40Z",
  "description": "SSH for device #001",
  "metadata": "",
  "addr": "1.tcp.ngrok.io:20006",
  "region": "us",
  "endpoint_configuration": null
}
Fields
id string

unique reserved address resource identifier

uri string

URI of the reserved address API resource

created_at string

timestamp when the reserved address was created, RFC 3339 format

description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

addr string

hostname:port of the reserved address that was assigned at creation time

region string

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

endpoint_configuration Ref

object reference to the endpoint configuration that will be applied to traffic to this address

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Delete Reserved Address

Delete a reserved address.

Request
DELETE/reserved_addrs/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ
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: 2" \
https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ
Response

Returns a 200 response on success

Example Response
{
  "id": "ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "created_at": "2021-10-20T12:07:40Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20006",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1zlnhWqRKTxwd4SS97m8Onl7cDi",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnhWqRKTxwd4SS97m8Onl7cDi"
  }
}
Fields
id string

unique reserved address resource identifier

uri string

URI of the reserved address API resource

created_at string

timestamp when the reserved address was created, RFC 3339 format

description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

addr string

hostname:port of the reserved address that was assigned at creation time

region string

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

endpoint_configuration Ref

object reference to the endpoint configuration that will be applied to traffic to this address

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
https://api.ngrok.com/reserved_addrs
Response

Returns a 200 response on success

Example Response
{
  "reserved_addrs": [
    {
      "id": "ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
      "uri": "https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
      "created_at": "2021-10-20T12:07:40Z",
      "description": "SSH for device #001",
      "metadata": "",
      "addr": "1.tcp.ngrok.io:20006",
      "region": "us",
      "endpoint_configuration": null
    }
  ],
  "uri": "https://api.ngrok.com/reserved_addrs",
  "next_page_uri": null
}
Fields
reserved_addrs ReservedAddr

the list of all reserved addresses on this account

uri string

URI of the reserved address list API resource

next_page_uri string

URI of the next page, or null if there is no next page

ReservedAddr fields
id string

unique reserved address resource identifier

uri string

URI of the reserved address API resource

created_at string

timestamp when the reserved address was created, RFC 3339 format

description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

addr string

hostname:port of the reserved address that was assigned at creation time

region string

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

endpoint_configuration Ref

object reference to the endpoint configuration that will be applied to traffic to this address

Ref fields
id string

a resource identifier

uri string

a uri for locating a 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: 2" \
-d '{"metadata":"{\"proto\": \"ssh\"}","endpoint_configuration_id":"ec_1zlnhWqRKTxwd4SS97m8Onl7cDi"}' \
https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ
Parameters
id string
description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

endpoint_configuration_id string

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_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1zll598FN4Pd61qUdWcDlyoa4WZ",
  "created_at": "2021-10-20T12:07:40Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20006",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1zlnhWqRKTxwd4SS97m8Onl7cDi",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlnhWqRKTxwd4SS97m8Onl7cDi"
  }
}
Fields
id string

unique reserved address resource identifier

uri string

URI of the reserved address API resource

created_at string

timestamp when the reserved address was created, RFC 3339 format

description string

human-readable description of what this reserved address will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

addr string

hostname:port of the reserved address that was assigned at creation time

region string

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

endpoint_configuration Ref

object reference to the endpoint configuration that will be applied to traffic to this address

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

Detach Endpoint Configuration from Reserved Address

Detach the endpoint configuration attached to a reserved address.

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

Returns a 204 response with no body on success

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: 2" \
-d '{"name":"myapp.mydomain.com","region":"us","certificate_id":"cert_1zlnghudbf2QxNkZNeaNSxnFQXy"}' \
https://api.ngrok.com/reserved_domains
Parameters
name string

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 string

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

http_endpoint_configuration_id string

ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain

https_endpoint_configuration_id string

ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain

certificate_id string

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with certificate_id.

ReservedDomainCertPolicy parameters
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "created_at": "2021-10-20T12:07:34Z",
  "description": "",
  "metadata": "",
  "domain": "myapp.mydomain.com",
  "region": "us",
  "cname_target": "356er6vjp.cname.us.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "certificate": {
    "id": "cert_1zlnghudbf2QxNkZNeaNSxnFQXy",
    "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnghudbf2QxNkZNeaNSxnFQXy"
  },
  "certificate_management_policy": null,
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}
Fields
id string

unique reserved domain resource identifier

uri string

URI of the reserved domain API resource

created_at string

timestamp when the reserved domain was created, RFC 3339 format

description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

domain string

hostname of the reserved domain

region string

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

cname_target string

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io

http_endpoint_configuration Ref

object referencing the endpoint configuration applied to http traffic on this domain

https_endpoint_configuration Ref

object referencing the endpoint configuration applied to https traffic on this domain

certificate Ref

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

certificate_management_status ReservedDomainCertStatus

status of the automatic certificate management for this domain, or null if automatic management is disabled

acme_challenge_cname_target string

DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

ReservedDomainCertPolicy fields
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields
renews_at string

timestamp when the next renewal will be requested, RFC 3339 format

provisioning_job ReservedDomainCertJob

status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields
error_code string

if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).

msg string

a message describing the current status or error

started_at string

timestamp when the provisioning job started, RFC 3339 format

retries_at string

timestamp when the provisioning job will be retried

Delete Reserved Domain

Delete a reserved domain.

Request
DELETE/reserved_domains/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur
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: 2" \
https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur
Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "created_at": "2021-10-20T12:07:34Z",
  "description": "point-of-sale new york #302",
  "metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
  "domain": "myapp.mydomain.com",
  "region": "us",
  "cname_target": "356er6vjp.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_1zlngwbEuZS8CykEZnqKSYEUf2B",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlngwbEuZS8CykEZnqKSYEUf2B"
  },
  "https_endpoint_configuration": {
    "id": "ec_1zlngvf3tLNCKhTztvQDB8rtTWo",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlngvf3tLNCKhTztvQDB8rtTWo"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}
Fields
id string

unique reserved domain resource identifier

uri string

URI of the reserved domain API resource

created_at string

timestamp when the reserved domain was created, RFC 3339 format

description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

domain string

hostname of the reserved domain

region string

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

cname_target string

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io

http_endpoint_configuration Ref

object referencing the endpoint configuration applied to http traffic on this domain

https_endpoint_configuration Ref

object referencing the endpoint configuration applied to https traffic on this domain

certificate Ref

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

certificate_management_status ReservedDomainCertStatus

status of the automatic certificate management for this domain, or null if automatic management is disabled

acme_challenge_cname_target string

DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

ReservedDomainCertPolicy fields
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields
renews_at string

timestamp when the next renewal will be requested, RFC 3339 format

provisioning_job ReservedDomainCertJob

status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields
error_code string

if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).

msg string

a message describing the current status or error

started_at string

timestamp when the provisioning job started, RFC 3339 format

retries_at string

timestamp when the provisioning job will be retried

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: 2" \
https://api.ngrok.com/reserved_domains
Response

Returns a 200 response on success

Example Response
{
  "reserved_domains": [
    {
      "id": "rd_1zlngn7wTZu2jpCSdVHOpEwtl7g",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1zlngn7wTZu2jpCSdVHOpEwtl7g",
      "created_at": "2021-10-20T12:07:35Z",
      "description": "Device 0001 Dashboard",
      "metadata": "{\"service\": \"dashboard\"}",
      "domain": "manage-0001.app.example.com",
      "region": "us",
      "cname_target": "7podqbqe.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": null,
      "certificate_management_policy": {
        "authority": "letsencrypt",
        "private_key_type": "ecdsa"
      },
      "certificate_management_status": {
        "renews_at": null,
        "provisioning_job": {
          "error_code": null,
          "msg": "Managed certificate provisioning in progress.",
          "started_at": "2021-10-20T12:07:35Z",
          "retries_at": null
        }
      },
      "acme_challenge_cname_target": null
    },
    {
      "id": "rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
      "created_at": "2021-10-20T12:07:34Z",
      "description": "",
      "metadata": "",
      "domain": "myapp.mydomain.com",
      "region": "us",
      "cname_target": "356er6vjp.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": {
        "id": "cert_1zlnghudbf2QxNkZNeaNSxnFQXy",
        "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnghudbf2QxNkZNeaNSxnFQXy"
      },
      "certificate_management_policy": null,
      "certificate_management_status": null,
      "acme_challenge_cname_target": null
    }
  ],
  "uri": "https://api.ngrok.com/reserved_domains",
  "next_page_uri": null
}
Fields
reserved_domains ReservedDomain

the list of all reserved domains on this account

uri string

URI of the reserved domain list API resource

next_page_uri string

URI of the next page, or null if there is no next page

ReservedDomain fields
id string

unique reserved domain resource identifier

uri string

URI of the reserved domain API resource

created_at string

timestamp when the reserved domain was created, RFC 3339 format

description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

domain string

hostname of the reserved domain

region string

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

cname_target string

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io

http_endpoint_configuration Ref

object referencing the endpoint configuration applied to http traffic on this domain

https_endpoint_configuration Ref

object referencing the endpoint configuration applied to https traffic on this domain

certificate Ref

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

certificate_management_status ReservedDomainCertStatus

status of the automatic certificate management for this domain, or null if automatic management is disabled

acme_challenge_cname_target string

DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

ReservedDomainCertPolicy fields
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields
renews_at string

timestamp when the next renewal will be requested, RFC 3339 format

provisioning_job ReservedDomainCertJob

status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields
error_code string

if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).

msg string

a message describing the current status or error

started_at string

timestamp when the provisioning job started, RFC 3339 format

retries_at string

timestamp when the provisioning job will be retried

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: 2" \
-d '{"description":"point-of-sale new york #302","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}","http_endpoint_configuration_id":"ec_1zlngwbEuZS8CykEZnqKSYEUf2B","https_endpoint_configuration_id":"ec_1zlngvf3tLNCKhTztvQDB8rtTWo","certificate_management_policy":{"authority":"letsencrypt"}}' \
https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur
Parameters
id string
description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

http_endpoint_configuration_id string

ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain

https_endpoint_configuration_id string

ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain

certificate_id string

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with certificate_id.

ReservedDomainCertPolicy parameters
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur",
  "created_at": "2021-10-20T12:07:34Z",
  "description": "point-of-sale new york #302",
  "metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
  "domain": "myapp.mydomain.com",
  "region": "us",
  "cname_target": "356er6vjp.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_1zlngwbEuZS8CykEZnqKSYEUf2B",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlngwbEuZS8CykEZnqKSYEUf2B"
  },
  "https_endpoint_configuration": {
    "id": "ec_1zlngvf3tLNCKhTztvQDB8rtTWo",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1zlngvf3tLNCKhTztvQDB8rtTWo"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}
Fields
id string

unique reserved domain resource identifier

uri string

URI of the reserved domain API resource

created_at string

timestamp when the reserved domain was created, RFC 3339 format

description string

human-readable description of what this reserved domain will be used for

metadata string

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

domain string

hostname of the reserved domain

region string

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

cname_target string

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io

http_endpoint_configuration Ref

object referencing the endpoint configuration applied to http traffic on this domain

https_endpoint_configuration Ref

object referencing the endpoint configuration applied to https traffic on this domain

certificate Ref

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 ReservedDomainCertPolicy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

certificate_management_status ReservedDomainCertStatus

status of the automatic certificate management for this domain, or null if automatic management is disabled

acme_challenge_cname_target string

DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

ReservedDomainCertPolicy fields
authority string

certificate authority to request certificates from. The only supported value is letsencrypt.

private_key_type string

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields
renews_at string

timestamp when the next renewal will be requested, RFC 3339 format

provisioning_job ReservedDomainCertJob

status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields
error_code string

if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).

msg string

a message describing the current status or error

started_at string

timestamp when the provisioning job started, RFC 3339 format

retries_at string

timestamp when the provisioning job will be retried

Detach Certificate Management Policy from Reserved Domain

Detach the certificate management policy attached to a reserved domain.

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

Returns a 204 response with no body on success

Detach Certificate from Reserved Domain

Detach the certificate attached to a reserved domain.

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

Returns a 204 response with no body on success

Detach HTTP Endpoint Configuration from Reserved Domain

Detach the http endpoint configuration attached to a reserved domain.

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

Returns a 204 response with no body on success

Detach HTTPS Endpoint Configuration from Reserved Domain

Detach the https endpoint configuration attached to a reserved domain.

Request
DELETE/reserved_domains/{id}/https_endpoint_configuration
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_1zlngdGQNR31rfGdG6bq7aL2Kur/https_endpoint_configuration
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: 2" \
-d '{"add":{"Cache-Control":"no-cache, no-store","X-XSS-Protection":"1; mode=block"}}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/response_headers
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from the HTTP Response returned to the HTTP client

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "add": {
    "cache-control": "no-cache, no-store",
    "x-xss-protection": "1; mode=block"
  },
  "remove": []
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from 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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/response_headers
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "add": {
    "cache-control": "no-cache, no-store",
    "x-xss-protection": "1; mode=block"
  },
  "remove": []
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

add Map<string, string>

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

remove List<string>

a list of header names that will be removed from 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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/response_headers
Response

Returns a 204 response with no body on success

Replace SAML Module

Request
PUT/endpoint_configurations/{id}/saml
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"idp_metadata":"\n\u003cEntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"\u003e\u003cIDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"\u003e\u003cNameIDFormat\u003eurn:oasis:names:tc:SAML:2.0:nameid-format:transient\u003c/NameIDFormat\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003c/IDPSSODescriptor\u003e\u003c/EntityDescriptor\u003e\n"}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/saml
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "options_passthrough": false,
  "cookie_prefix": "",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "idp_metadata_url": "",
  "idp_metadata": "\n\u003cEntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"\u003e\u003cIDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"\u003e\u003cNameIDFormat\u003eurn:oasis:names:tc:SAML:2.0:nameid-format:transient\u003c/NameIDFormat\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003c/IDPSSODescriptor\u003e\u003c/EntityDescriptor\u003e\n",
  "force_authn": false,
  "allow_idp_initiated": true,
  "authorized_groups": [],
  "entity_id": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu",
  "assertion_consumer_service_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/acs",
  "single_logout_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIID5DCCAsygAwIBAgIRANuk7IDZY/9Z/pbeJfBv+dswDQYJKoZIhvcNAQELBQAw\ngZAxRjBEBgNVBAoMPWh0dHBzOi8vaWRwLm5ncm9rLmNvbS5sYW4vc2FtbC9lY18x\nemxua1NxcVlCWjdtMldCc1Q3TjREb04yWXUxRjBEBgNVBAMMPWh0dHBzOi8vaWRw\nLm5ncm9rLmNvbS5sYW4vc2FtbC9lY18xemxua1NxcVlCWjdtMldCc1Q3TjREb04y\nWXUwIBcNMjExMDIwMTIwODI0WhgPMjA1NjEwMTExMjA4MjRaMIGQMUYwRAYDVQQK\nDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFuL3NhbWwvZWNfMXpsbmtTcXFZQlo3\nbTJXQnNUN040RG9OMll1MUYwRAYDVQQDDD1odHRwczovL2lkcC5uZ3Jvay5jb20u\nbGFuL3NhbWwvZWNfMXpsbmtTcXFZQlo3bTJXQnNUN040RG9OMll1MIIBIjANBgkq\nhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxrKga5qgdJTbmAN71qJYQ/w+GgqI/Lmw\nxacx2u9mPhKygQImIJ1XF3ySYpZnsM4A9ZwKGa5vsilFX1ScvPT5wxlcga/ly0iL\nfsgIamubGAPLN6W/RwoIldYeLT0Z+YEFDTK20ohae6sZTEgxvrQgXE9w4RHG8Emm\n3wKEMcVEm15/R0H330Dw7aYBR5/qsfNth/9lMHawDLaH/XCRaFjJgbQqs8HbbP6k\nerwvx6KaNm5opFM/IXNcOn7jaAte/T/uql58Op39y14MtspDlCwWiSZOK16SGkMu\nv9ISbRjRF21WupIafkJ2hWY/IMH/WUQI2ASu5KlK8ABpviqfMre0bwIDAQABozUw\nMzAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDAYDVR0TAQH/\nBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAXZpWnDI0XVdWnHVKXLxyHXGYJpSIDqZ6\nM8pcwE9Kns/CVeuo7w2AdgqjvcaR4opWF40vD2BSEcrXMLM89LDppvcNRl2XXDip\no36F/erLueTK6cunHLmny7l0aeZoPjomrlO4sXZOu7VsSvOOlg2QJ0EO9S2k/2Wi\nperpD5JRABN5uhG5MFWbjD9pZXnRhYc8r/chrAwVRjrlgf2b8yVfaV9l+Sqr/o8F\ncED8NSh+q3SHOxKKmgGvKKUtzqn55qj9ZdNduSuWbQSzH81qSS+M+P2neHWvEJJI\ng3UEOGtmZRUPJX7aE296A2R7CmdyZxX13t8DekbLj+Wjr/h9c/DbuA==\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu",
  "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Get SAML Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "options_passthrough": false,
  "cookie_prefix": "",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "idp_metadata_url": "",
  "idp_metadata": "\n\u003cEntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"\u003e\u003cIDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"\u003e\u003cNameIDFormat\u003eurn:oasis:names:tc:SAML:2.0:nameid-format:transient\u003c/NameIDFormat\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003c/IDPSSODescriptor\u003e\u003c/EntityDescriptor\u003e\n",
  "force_authn": false,
  "allow_idp_initiated": true,
  "authorized_groups": [],
  "entity_id": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu",
  "assertion_consumer_service_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/acs",
  "single_logout_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIID5DCCAsygAwIBAgIRANuk7IDZY/9Z/pbeJfBv+dswDQYJKoZIhvcNAQELBQAw\ngZAxRjBEBgNVBAoMPWh0dHBzOi8vaWRwLm5ncm9rLmNvbS5sYW4vc2FtbC9lY18x\nemxua1NxcVlCWjdtMldCc1Q3TjREb04yWXUxRjBEBgNVBAMMPWh0dHBzOi8vaWRw\nLm5ncm9rLmNvbS5sYW4vc2FtbC9lY18xemxua1NxcVlCWjdtMldCc1Q3TjREb04y\nWXUwIBcNMjExMDIwMTIwODI0WhgPMjA1NjEwMTExMjA4MjRaMIGQMUYwRAYDVQQK\nDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFuL3NhbWwvZWNfMXpsbmtTcXFZQlo3\nbTJXQnNUN040RG9OMll1MUYwRAYDVQQDDD1odHRwczovL2lkcC5uZ3Jvay5jb20u\nbGFuL3NhbWwvZWNfMXpsbmtTcXFZQlo3bTJXQnNUN040RG9OMll1MIIBIjANBgkq\nhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxrKga5qgdJTbmAN71qJYQ/w+GgqI/Lmw\nxacx2u9mPhKygQImIJ1XF3ySYpZnsM4A9ZwKGa5vsilFX1ScvPT5wxlcga/ly0iL\nfsgIamubGAPLN6W/RwoIldYeLT0Z+YEFDTK20ohae6sZTEgxvrQgXE9w4RHG8Emm\n3wKEMcVEm15/R0H330Dw7aYBR5/qsfNth/9lMHawDLaH/XCRaFjJgbQqs8HbbP6k\nerwvx6KaNm5opFM/IXNcOn7jaAte/T/uql58Op39y14MtspDlCwWiSZOK16SGkMu\nv9ISbRjRF21WupIafkJ2hWY/IMH/WUQI2ASu5KlK8ABpviqfMre0bwIDAQABozUw\nMzAOBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDAYDVR0TAQH/\nBAIwADANBgkqhkiG9w0BAQsFAAOCAQEAXZpWnDI0XVdWnHVKXLxyHXGYJpSIDqZ6\nM8pcwE9Kns/CVeuo7w2AdgqjvcaR4opWF40vD2BSEcrXMLM89LDppvcNRl2XXDip\no36F/erLueTK6cunHLmny7l0aeZoPjomrlO4sXZOu7VsSvOOlg2QJ0EO9S2k/2Wi\nperpD5JRABN5uhG5MFWbjD9pZXnRhYc8r/chrAwVRjrlgf2b8yVfaV9l+Sqr/o8F\ncED8NSh+q3SHOxKKmgGvKKUtzqn55qj9ZdNduSuWbQSzH81qSS+M+P2neHWvEJJI\ng3UEOGtmZRUPJX7aE296A2R7CmdyZxX13t8DekbLj+Wjr/h9c/DbuA==\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.ngrok.com/saml/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu",
  "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

options_passthrough boolean

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

cookie_prefix string

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

inactivity_timeout uint32

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 uint32

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

idp_metadata string

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

force_authn boolean

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

allow_idp_initiated boolean

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

authorized_groups List<string>

If present, only users who are a member of one of the listed groups may access the target endpoint.

entity_id string

The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.

assertion_consumer_service_url string

The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.

single_logout_url string

The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.

request_signing_certificate_pem string

PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.

metadata_url string

A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.

nameid_format string

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Delete SAML Module

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

Returns a 204 response with no body on success

Create SSH Certificate Authority

Create a new SSH Certificate Authority

Request
POST/ssh_certificate_authorities
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"Staging Environment Hosts","private_key_type":"ed25519"}' \
https://api.ngrok.com/ssh_certificate_authorities
Parameters
description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

private_key_type string

the type of private key to generate. one of rsa, ecdsa, ed25519

elliptic_curve string

the type of elliptic curve to use when creating an ECDSA key

key_size int64

the key size to use when creating an RSA key. one of 2048 or 4096

Response

Returns a 200 response on success

Example Response
{
  "id": "sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "created_at": "2021-10-20T12:08:49Z",
  "description": "Staging Environment Hosts",
  "metadata": "",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOiZqsskENMOeFE3M4ycy2N93I7m9XJT/GctHNt4byoy",
  "key_type": "ed25519"
}
Fields
id string

unique identifier for this SSH Certificate Authority

uri string

URI of the SSH Certificate Authority API resource

created_at string

timestamp when the SSH Certificate Authority API resource was created, RFC 3339 format

description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

public_key string

raw public key for this SSH Certificate Authority

key_type string

the type of private key for this SSH Certificate Authority

Delete SSH Certificate Authority

Delete an SSH Certificate Authority

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

Returns a 204 response with no body on success

Get SSH Certificate Authority

Get detailed information about an SSH Certficate Authority

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

Returns a 200 response on success

Example Response
{
  "id": "sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "created_at": "2021-10-20T12:08:49Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOiZqsskENMOeFE3M4ycy2N93I7m9XJT/GctHNt4byoy",
  "key_type": "ed25519"
}
Fields
id string

unique identifier for this SSH Certificate Authority

uri string

URI of the SSH Certificate Authority API resource

created_at string

timestamp when the SSH Certificate Authority API resource was created, RFC 3339 format

description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

public_key string

raw public key for this SSH Certificate Authority

key_type string

the type of private key for this SSH Certificate Authority

List SSH Certificate Authorities

List all SSH Certificate Authorities on this account

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

Returns a 200 response on success

Example Response
{
  "ssh_certificate_authorities": [
    {
      "id": "sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
      "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
      "created_at": "2021-10-20T12:08:49Z",
      "description": "Staging Environment Hosts",
      "metadata": "",
      "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOiZqsskENMOeFE3M4ycy2N93I7m9XJT/GctHNt4byoy",
      "key_type": "ed25519"
    }
  ],
  "uri": "https://api.ngrok.com/ssh_certificate_authorities",
  "next_page_uri": null
}
Fields
ssh_certificate_authorities SSHCertificateAuthority

the list of all certificate authorities on this account

uri string

URI of the certificates authorities list API resource

next_page_uri string

URI of the next page, or null if there is no next page

SSHCertificateAuthority fields
id string

unique identifier for this SSH Certificate Authority

uri string

URI of the SSH Certificate Authority API resource

created_at string

timestamp when the SSH Certificate Authority API resource was created, RFC 3339 format

description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

public_key string

raw public key for this SSH Certificate Authority

key_type string

the type of private key for this SSH Certificate Authority

Update SSH Certificate Authority

Update an SSH Certificate Authority

Request
PATCH/ssh_certificate_authorities/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"region\": \"us-east-1\"}"}' \
https://api.ngrok.com/ssh_certificate_authorities/sshca_1zlnq505r4BemBYyxRkTrwL0vDD
Parameters
id string
description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1zlnq505r4BemBYyxRkTrwL0vDD",
  "created_at": "2021-10-20T12:08:49Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOiZqsskENMOeFE3M4ycy2N93I7m9XJT/GctHNt4byoy",
  "key_type": "ed25519"
}
Fields
id string

unique identifier for this SSH Certificate Authority

uri string

URI of the SSH Certificate Authority API resource

created_at string

timestamp when the SSH Certificate Authority API resource was created, RFC 3339 format

description string

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

public_key string

raw public key for this SSH Certificate Authority

key_type string

the type of private key for this SSH Certificate Authority

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: 2" \
-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 string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

acl List<string>

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 string

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_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "created_at": "2021-10-20T12:07:53Z",
  "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 string

unique ssh credential resource identifier

uri string

URI of the ssh credential API resource

created_at string

timestamp when the ssh credential was created, RFC 3339 format

description string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

public_key string

the PEM-encoded public key of the SSH keypair that will be used to authenticate

acl List<string>

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: 2" \
https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL
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: 2" \
https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL
Response

Returns a 200 response on success

Example Response
{
  "id": "sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "created_at": "2021-10-20T12:07:53Z",
  "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 string

unique ssh credential resource identifier

uri string

URI of the ssh credential API resource

created_at string

timestamp when the ssh credential was created, RFC 3339 format

description string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

public_key string

the PEM-encoded public key of the SSH keypair that will be used to authenticate

acl List<string>

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: 2" \
https://api.ngrok.com/ssh_credentials
Response

Returns a 200 response on success

Example Response
{
  "ssh_credentials": [
    {
      "id": "sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
      "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
      "created_at": "2021-10-20T12:07:53Z",
      "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",
  "next_page_uri": null
}
Fields
ssh_credentials SSHCredential

the list of all ssh credentials on this account

uri string

URI of the ssh credential list API resource

next_page_uri string

URI of the next page, or null if there is no next page

SSHCredential fields
id string

unique ssh credential resource identifier

uri string

URI of the ssh credential API resource

created_at string

timestamp when the ssh credential was created, RFC 3339 format

description string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

public_key string

the PEM-encoded public key of the SSH keypair that will be used to authenticate

acl List<string>

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.

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: 2" \
-d '{"description":"my dev machine","metadata":"{\"hostname\": \"macbook.local\"}"}' \
https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL
Parameters
id string
description string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

acl List<string>

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_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1zlnj6IrIX0tAu4UGmxqNMcdMlL",
  "created_at": "2021-10-20T12:07:53Z",
  "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 string

unique ssh credential resource identifier

uri string

URI of the ssh credential API resource

created_at string

timestamp when the ssh credential was created, RFC 3339 format

description string

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

public_key string

the PEM-encoded public key of the SSH keypair that will be used to authenticate

acl List<string>

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 SSH Host Certificate

Create a new SSH Host Certificate

Request
POST/ssh_host_certificates
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"ssh_certificate_authority_id":"sshca_1zlnquH3wP44YahyYHwi0wvTzmk","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com","principals":["inconshreveable.com","10.2.42.9"],"valid_until":"2022-01-18T12:08:55Z","description":"personal server"}' \
https://api.ngrok.com/ssh_host_certificates
Parameters
ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh host certificate

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

principals List<string>

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

valid_after string

The time when the host certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.

valid_until string

The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of one year in the future will be used. The OpenSSH certificates RFC calls this valid_before.

description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "created_at": "2021-10-20T12:08:55Z",
  "description": "personal server",
  "metadata": "",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnquH3wP44YahyYHwi0wvTzmk",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-10-20T12:08:55Z",
  "valid_until": "2022-01-18T12:08:55Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkc++0E6u01aSDxKwGfEvORzT288pRoPtr+fEuUQYtDgAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXpsbnFwcEFZUENqclY1dzdtaERKUzl1NEhWAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABhcAbXAAAAAGHmrdcAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIBwMgTb3XT4H7E07fCVCRvIOJzS2xjEji6lxrWkl6AVJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEBfMV6CTukPvuEdMfhk2798RvTOxznzQaHcwUGV//pHb6G5XBJEStk0zCMIcc2KjqJ1uzP9QhY1mku28PrYyN8G shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV"
}
Fields
id string

unique identifier for this SSH Host Certificate

uri string

URI of the SSH Host Certificate API resource

created_at string

timestamp when the SSH Host Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh host certificate

principals List<string>

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Delete SSH Host Certificate

Delete an SSH Host Certificate

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

Returns a 204 response with no body on success

Get SSH Host Certificate

Get detailed information about an SSH Host Certficate

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

Returns a 200 response on success

Example Response
{
  "id": "shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "created_at": "2021-10-20T12:08:55Z",
  "description": "personal server",
  "metadata": "{\"region\": \"us-west-2\"}",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnquH3wP44YahyYHwi0wvTzmk",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-10-20T12:08:55Z",
  "valid_until": "2022-01-18T12:08:55Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkc++0E6u01aSDxKwGfEvORzT288pRoPtr+fEuUQYtDgAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXpsbnFwcEFZUENqclY1dzdtaERKUzl1NEhWAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABhcAbXAAAAAGHmrdcAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIBwMgTb3XT4H7E07fCVCRvIOJzS2xjEji6lxrWkl6AVJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEBfMV6CTukPvuEdMfhk2798RvTOxznzQaHcwUGV//pHb6G5XBJEStk0zCMIcc2KjqJ1uzP9QhY1mku28PrYyN8G shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV"
}
Fields
id string

unique identifier for this SSH Host Certificate

uri string

URI of the SSH Host Certificate API resource

created_at string

timestamp when the SSH Host Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh host certificate

principals List<string>

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

List SSH Host Certificates

List all SSH Host Certificates issued on this account

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

Returns a 200 response on success

Example Response
{
  "ssh_host_certificates": [
    {
      "id": "shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
      "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
      "created_at": "2021-10-20T12:08:55Z",
      "description": "personal server",
      "metadata": "",
      "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
      "key_type": "ecdsa",
      "ssh_certificate_authority_id": "sshca_1zlnquH3wP44YahyYHwi0wvTzmk",
      "principals": [
        "inconshreveable.com",
        "10.2.42.9"
      ],
      "valid_after": "2021-10-20T12:08:55Z",
      "valid_until": "2022-01-18T12:08:55Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkc++0E6u01aSDxKwGfEvORzT288pRoPtr+fEuUQYtDgAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXpsbnFwcEFZUENqclY1dzdtaERKUzl1NEhWAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABhcAbXAAAAAGHmrdcAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIBwMgTb3XT4H7E07fCVCRvIOJzS2xjEji6lxrWkl6AVJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEBfMV6CTukPvuEdMfhk2798RvTOxznzQaHcwUGV//pHb6G5XBJEStk0zCMIcc2KjqJ1uzP9QhY1mku28PrYyN8G shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV"
    }
  ],
  "uri": "https://api.ngrok.com/ssh_host_certificates",
  "next_page_uri": null
}
Fields
ssh_host_certificates SSHHostCertificate

the list of all ssh host certificates on this account

uri string

URI of the ssh host certificates list API resource

next_page_uri string

URI of the next page, or null if there is no next page

SSHHostCertificate fields
id string

unique identifier for this SSH Host Certificate

uri string

URI of the SSH Host Certificate API resource

created_at string

timestamp when the SSH Host Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh host certificate

principals List<string>

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Update SSH Host Certificate

Update an SSH Host Certificate

Request
PATCH/ssh_host_certificates/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"region\": \"us-west-2\"}"}' \
https://api.ngrok.com/ssh_host_certificates/shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV
Parameters
id string
description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV",
  "created_at": "2021-10-20T12:08:55Z",
  "description": "personal server",
  "metadata": "{\"region\": \"us-west-2\"}",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnquH3wP44YahyYHwi0wvTzmk",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-10-20T12:08:55Z",
  "valid_until": "2022-01-18T12:08:55Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkc++0E6u01aSDxKwGfEvORzT288pRoPtr+fEuUQYtDgAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXpsbnFwcEFZUENqclY1dzdtaERKUzl1NEhWAAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABhcAbXAAAAAGHmrdcAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIBwMgTb3XT4H7E07fCVCRvIOJzS2xjEji6lxrWkl6AVJAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEBfMV6CTukPvuEdMfhk2798RvTOxznzQaHcwUGV//pHb6G5XBJEStk0zCMIcc2KjqJ1uzP9QhY1mku28PrYyN8G shcrt_1zlnqppAYPCjrV5w7mhDJS9u4HV"
}
Fields
id string

unique identifier for this SSH Host Certificate

uri string

URI of the SSH Host Certificate API resource

created_at string

timestamp when the SSH Host Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh host certificate

principals List<string>

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Create SSH User Certificate

Create a new SSH User Certificate

Request
POST/ssh_user_certificates
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"ssh_certificate_authority_id":"sshca_1zlnqUSw3V8cYowsHnEvshKLadh","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop","principals":["ec2-user","root"],"valid_until":"2022-01-18T12:08:52Z","description":"temporary access to staging machine"}' \
https://api.ngrok.com/ssh_user_certificates
Parameters
ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh user certificate

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

principals List<string>

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

critical_options Map<string, string>

A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.

extensions Map<string, string>

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.

valid_after string

The time when the user certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.

valid_until string

The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of 24 hours will be used. The OpenSSH certificates RFC calls this valid_before.

description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "created_at": "2021-10-20T12:08:52Z",
  "description": "temporary access to staging machine",
  "metadata": "",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnqUSw3V8cYowsHnEvshKLadh",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-10-20T12:08:52Z",
  "valid_until": "2022-01-18T12:08:52Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkCtnOCjCTzsAuBlmfiD+Occi0CyYK5G7BIHQxij2XswAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXpsbnFYaFFic0RkNG1KaDRaejdPRnRJbTVGAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGFwBtQAAAAAYeat1AAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIPreDviOEyAr5rGk5UIH+yOzV20G5/7MFjUZy6X5abcCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDNjF4v3G/o7QqB9Y+owC+bmcyxhXQiCW61CKZK2ic4Kg49UFY4WUrq0Jk5IpjoyW8is1ARvcLHUDV6IQRTgnoK sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F"
}
Fields
id string

unique identifier for this SSH User Certificate

uri string

URI of the SSH User Certificate API resource

created_at string

timestamp when the SSH User Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh user certificate

principals List<string>

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

critical_options Map<string, string>

A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.

extensions Map<string, string>

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Delete SSH User Certificate

Delete an SSH User Certificate

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

Returns a 204 response with no body on success

Get SSH User Certificate

Get detailed information about an SSH User Certficate

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

Returns a 200 response on success

Example Response
{
  "id": "sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "created_at": "2021-10-20T12:08:52Z",
  "description": "temporary access to staging machine for alan",
  "metadata": "{\"user_email\": \"alan@example.com\"}",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnqUSw3V8cYowsHnEvshKLadh",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-10-20T12:08:52Z",
  "valid_until": "2022-01-18T12:08:52Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkCtnOCjCTzsAuBlmfiD+Occi0CyYK5G7BIHQxij2XswAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXpsbnFYaFFic0RkNG1KaDRaejdPRnRJbTVGAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGFwBtQAAAAAYeat1AAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIPreDviOEyAr5rGk5UIH+yOzV20G5/7MFjUZy6X5abcCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDNjF4v3G/o7QqB9Y+owC+bmcyxhXQiCW61CKZK2ic4Kg49UFY4WUrq0Jk5IpjoyW8is1ARvcLHUDV6IQRTgnoK sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F"
}
Fields
id string

unique identifier for this SSH User Certificate

uri string

URI of the SSH User Certificate API resource

created_at string

timestamp when the SSH User Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh user certificate

principals List<string>

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

critical_options Map<string, string>

A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.

extensions Map<string, string>

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

List SSH User Certificates

List all SSH User Certificates issued on this account

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

Returns a 200 response on success

Example Response
{
  "ssh_user_certificates": [
    {
      "id": "sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
      "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
      "created_at": "2021-10-20T12:08:52Z",
      "description": "temporary access to staging machine",
      "metadata": "",
      "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
      "key_type": "ecdsa",
      "ssh_certificate_authority_id": "sshca_1zlnqUSw3V8cYowsHnEvshKLadh",
      "principals": [
        "ec2-user",
        "root"
      ],
      "critical_options": {},
      "extensions": {
        "permit-pty": "",
        "permit-user-rc": ""
      },
      "valid_after": "2021-10-20T12:08:52Z",
      "valid_until": "2022-01-18T12:08:52Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkCtnOCjCTzsAuBlmfiD+Occi0CyYK5G7BIHQxij2XswAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXpsbnFYaFFic0RkNG1KaDRaejdPRnRJbTVGAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGFwBtQAAAAAYeat1AAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIPreDviOEyAr5rGk5UIH+yOzV20G5/7MFjUZy6X5abcCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDNjF4v3G/o7QqB9Y+owC+bmcyxhXQiCW61CKZK2ic4Kg49UFY4WUrq0Jk5IpjoyW8is1ARvcLHUDV6IQRTgnoK sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F"
    }
  ],
  "uri": "https://api.ngrok.com/ssh_user_certificates",
  "next_page_uri": null
}
Fields
ssh_user_certificates SSHUserCertificate

the list of all ssh user certificates on this account

uri string

URI of the ssh user certificates list API resource

next_page_uri string

URI of the next page, or null if there is no next page

SSHUserCertificate fields
id string

unique identifier for this SSH User Certificate

uri string

URI of the SSH User Certificate API resource

created_at string

timestamp when the SSH User Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh user certificate

principals List<string>

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

critical_options Map<string, string>

A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.

extensions Map<string, string>

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

Update SSH User Certificate

Update an SSH User Certificate

Request
PATCH/ssh_user_certificates/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"temporary access to staging machine for alan","metadata":"{\"user_email\": \"alan@example.com\"}"}' \
https://api.ngrok.com/ssh_user_certificates/sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F
Parameters
id string
description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

Response

Returns a 200 response on success

Example Response
{
  "id": "sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F",
  "created_at": "2021-10-20T12:08:52Z",
  "description": "temporary access to staging machine for alan",
  "metadata": "{\"user_email\": \"alan@example.com\"}",
  "public_key": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop",
  "key_type": "ecdsa",
  "ssh_certificate_authority_id": "sshca_1zlnqUSw3V8cYowsHnEvshKLadh",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-10-20T12:08:52Z",
  "valid_until": "2022-01-18T12:08:52Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgkCtnOCjCTzsAuBlmfiD+Occi0CyYK5G7BIHQxij2XswAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXpsbnFYaFFic0RkNG1KaDRaejdPRnRJbTVGAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGFwBtQAAAAAYeat1AAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIPreDviOEyAr5rGk5UIH+yOzV20G5/7MFjUZy6X5abcCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDNjF4v3G/o7QqB9Y+owC+bmcyxhXQiCW61CKZK2ic4Kg49UFY4WUrq0Jk5IpjoyW8is1ARvcLHUDV6IQRTgnoK sucrt_1zlnqXhQbsDd4mJh4Zz7OFtIm5F"
}
Fields
id string

unique identifier for this SSH User Certificate

uri string

URI of the SSH User Certificate API resource

created_at string

timestamp when the SSH User Certificate API resource was created, RFC 3339 format

description string

human-readable description of this SSH User Certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

public_key string

a public key in OpenSSH Authorized Keys format that this certificate signs

key_type string

the key type of the public_key, one of rsa, ecdsa or ed25519

ssh_certificate_authority_id string

the ssh certificate authority that is used to sign this ssh user certificate

principals List<string>

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

critical_options Map<string, string>

A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.

extensions Map<string, string>

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.

valid_after string

the time when the ssh host certificate becomes valid, in RFC 3339 format.

valid_until string

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

certificate string

the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive

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: 2" \
-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 string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

certificate_pem string

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

private_key_pem string

private key for the TLS certificate, PEM-encoded. See Private Keys.

Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "created_at": "2021-10-20T12:08:31Z",
  "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",
  "subject_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",
  "issuer_common_name": "example.com",
  "serial_number": "054ba70dd03882382d11b640f30f4b8e1be5ddb1",
  "subject_organization": "",
  "subject_organizational_unit": "",
  "subject_locality": "",
  "subject_province": "",
  "subject_country": ""
}
Fields
id string

unique identifier for this TLS certificate

uri string

URI of the TLS certificate API resource

created_at string

timestamp when the TLS certificate was created, RFC 3339 format

description string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

certificate_pem string

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

subject_common_name string

subject common name from the leaf of this TLS certificate

subject_alternative_names TLSCertificateSANs

subject alternative names (SANs) from the leaf of this TLS certificate

issued_at string

timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded

not_before string

timestamp when this TLS certificate becomes valid, RFC 3339 format

not_after string

timestamp when this TLS certificate becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this TLS certificate can be used for

extended_key_usages List<string>

extended set of actions the private key of this TLS certificate can be used for

private_key_type string

type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

issuer_common_name string

issuer common name from the leaf of this TLS certificate

serial_number string

serial number of the leaf of this TLS certificate

subject_organization string

subject organization from the leaf of this TLS certificate

subject_organizational_unit string

subject organizational unit from the leaf of this TLS certificate

subject_locality string

subject locality from the leaf of this TLS certificate

subject_province string

subject province from the leaf of this TLS certificate

subject_country string

subject country from the leaf of this TLS certificate

TLSCertificateSANs fields
dns_names List<string>

set of additional domains (including wildcards) this TLS certificate is valid for

ips List<string>

set of IP addresses this TLS certificate is also valid for

Delete TLS Certificate

Delete a TLS certificate

Request
DELETE/tls_certificates/{id}
Example Request
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk
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: 2" \
https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk
Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "created_at": "2021-10-20T12:08:31Z",
  "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",
  "subject_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",
  "issuer_common_name": "example.com",
  "serial_number": "054ba70dd03882382d11b640f30f4b8e1be5ddb1",
  "subject_organization": "",
  "subject_organizational_unit": "",
  "subject_locality": "",
  "subject_province": "",
  "subject_country": ""
}
Fields
id string

unique identifier for this TLS certificate

uri string

URI of the TLS certificate API resource

created_at string

timestamp when the TLS certificate was created, RFC 3339 format

description string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

certificate_pem string

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

subject_common_name string

subject common name from the leaf of this TLS certificate

subject_alternative_names TLSCertificateSANs

subject alternative names (SANs) from the leaf of this TLS certificate

issued_at string

timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded

not_before string

timestamp when this TLS certificate becomes valid, RFC 3339 format

not_after string

timestamp when this TLS certificate becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this TLS certificate can be used for

extended_key_usages List<string>

extended set of actions the private key of this TLS certificate can be used for

private_key_type string

type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

issuer_common_name string

issuer common name from the leaf of this TLS certificate

serial_number string

serial number of the leaf of this TLS certificate

subject_organization string

subject organization from the leaf of this TLS certificate

subject_organizational_unit string

subject organizational unit from the leaf of this TLS certificate

subject_locality string

subject locality from the leaf of this TLS certificate

subject_province string

subject province from the leaf of this TLS certificate

subject_country string

subject country from the leaf of this TLS certificate

TLSCertificateSANs fields
dns_names List<string>

set of additional domains (including wildcards) this TLS certificate is valid for

ips List<string>

set of IP addresses this TLS certificate is also valid for

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: 2" \
https://api.ngrok.com/tls_certificates
Response

Returns a 200 response on success

Example Response
{
  "tls_certificates": [
    {
      "id": "cert_1zlnghudbf2QxNkZNeaNSxnFQXy",
      "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnghudbf2QxNkZNeaNSxnFQXy",
      "created_at": "2021-10-20T12:07:34Z",
      "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",
      "subject_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",
      "issuer_common_name": "example.com",
      "serial_number": "054ba70dd03882382d11b640f30f4b8e1be5ddb1",
      "subject_organization": "",
      "subject_organizational_unit": "",
      "subject_locality": "",
      "subject_province": "",
      "subject_country": ""
    },
    {
      "id": "cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
      "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
      "created_at": "2021-10-20T12:08:31Z",
      "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",
      "subject_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",
      "issuer_common_name": "example.com",
      "serial_number": "054ba70dd03882382d11b640f30f4b8e1be5ddb1",
      "subject_organization": "",
      "subject_organizational_unit": "",
      "subject_locality": "",
      "subject_province": "",
      "subject_country": ""
    }
  ],
  "uri": "https://api.ngrok.com/tls_certificates",
  "next_page_uri": null
}
Fields
tls_certificates TLSCertificate

the list of all TLS certificates on this account

uri string

URI of the TLS certificates list API resource

next_page_uri string

URI of the next page, or null if there is no next page

TLSCertificate fields
id string

unique identifier for this TLS certificate

uri string

URI of the TLS certificate API resource

created_at string

timestamp when the TLS certificate was created, RFC 3339 format

description string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

certificate_pem string

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

subject_common_name string

subject common name from the leaf of this TLS certificate

subject_alternative_names TLSCertificateSANs

subject alternative names (SANs) from the leaf of this TLS certificate

issued_at string

timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded

not_before string

timestamp when this TLS certificate becomes valid, RFC 3339 format

not_after string

timestamp when this TLS certificate becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this TLS certificate can be used for

extended_key_usages List<string>

extended set of actions the private key of this TLS certificate can be used for

private_key_type string

type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

issuer_common_name string

issuer common name from the leaf of this TLS certificate

serial_number string

serial number of the leaf of this TLS certificate

subject_organization string

subject organization from the leaf of this TLS certificate

subject_organizational_unit string

subject organizational unit from the leaf of this TLS certificate

subject_locality string

subject locality from the leaf of this TLS certificate

subject_province string

subject province from the leaf of this TLS certificate

subject_country string

subject country from the leaf of this TLS certificate

TLSCertificateSANs fields
dns_names List<string>

set of additional domains (including wildcards) this TLS certificate is valid for

ips List<string>

set of IP addresses this TLS certificate is also valid for

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: 2" \
-d '{"metadata":"{\"example\": true}"}' \
https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk
Parameters
id string
description string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

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_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1zlnnqSwc2cCARkjbP1QDnnwcBk",
  "created_at": "2021-10-20T12:08:31Z",
  "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",
  "subject_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",
  "issuer_common_name": "example.com",
  "serial_number": "054ba70dd03882382d11b640f30f4b8e1be5ddb1",
  "subject_organization": "",
  "subject_organizational_unit": "",
  "subject_locality": "",
  "subject_province": "",
  "subject_country": ""
}
Fields
id string

unique identifier for this TLS certificate

uri string

URI of the TLS certificate API resource

created_at string

timestamp when the TLS certificate was created, RFC 3339 format

description string

human-readable description of this TLS certificate. optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

certificate_pem string

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

subject_common_name string

subject common name from the leaf of this TLS certificate

subject_alternative_names TLSCertificateSANs

subject alternative names (SANs) from the leaf of this TLS certificate

issued_at string

timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded

not_before string

timestamp when this TLS certificate becomes valid, RFC 3339 format

not_after string

timestamp when this TLS certificate becomes invalid, RFC 3339 format

key_usages List<string>

set of actions the private key of this TLS certificate can be used for

extended_key_usages List<string>

extended set of actions the private key of this TLS certificate can be used for

private_key_type string

type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

issuer_common_name string

issuer common name from the leaf of this TLS certificate

serial_number string

serial number of the leaf of this TLS certificate

subject_organization string

subject organization from the leaf of this TLS certificate

subject_organizational_unit string

subject organizational unit from the leaf of this TLS certificate

subject_locality string

subject locality from the leaf of this TLS certificate

subject_province string

subject province from the leaf of this TLS certificate

subject_country string

subject country from the leaf of this TLS certificate

TLSCertificateSANs fields
dns_names List<string>

set of additional domains (including wildcards) this TLS certificate is valid for

ips List<string>

set of IP addresses this TLS certificate is also valid for

Replace TLS Termination Module

Request
PUT/endpoint_configurations/{id}/tls_termination
Example Request
curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"terminate_at":"edge","min_version":"1.2"}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/tls_termination
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "terminate_at": "edge",
  "min_version": "1.2"
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

Get TLS Termination Module

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

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "terminate_at": "edge",
  "min_version": "1.2"
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

terminate_at string

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

min_version string

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. This value must be null if terminate_at is set to upstream.

Delete TLS Termination Module

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

Returns a 204 response with no body on success

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: 2" \
-d '{"description":"development cred for alan@example.com"}' \
https://api.ngrok.com/credentials
Parameters
description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

acl List<string>

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_1zlnhsWjU708R6U0zrarw8LQi9T",
  "uri": "https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T",
  "created_at": "2021-10-20T12:07:43Z",
  "description": "development cred for alan@example.com",
  "metadata": "",
  "token": "1zlnhsWjU708R6U0zrarw8LQi9T_6nzPMZHL7mMxtnS4bX8a2",
  "acl": []
}
Fields
id string

unique tunnel credential resource identifier

uri string

URI of the tunnel credential API resource

created_at string

timestamp when the tunnel credential was created, RFC 3339 format

description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

token string

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 List<string>

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: 2" \
https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T
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: 2" \
https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T
Response

Returns a 200 response on success

Example Response
{
  "id": "cr_1zlnhsWjU708R6U0zrarw8LQi9T",
  "uri": "https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T",
  "created_at": "2021-10-20T12:07:43Z",
  "description": "device alpha-2",
  "metadata": "{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}",
  "token": null,
  "acl": []
}
Fields
id string

unique tunnel credential resource identifier

uri string

URI of the tunnel credential API resource

created_at string

timestamp when the tunnel credential was created, RFC 3339 format

description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

token string

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 List<string>

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: 2" \
https://api.ngrok.com/credentials
Response

Returns a 200 response on success

Example Response
{
  "credentials": [
    {
      "id": "cr_1zlnhsWjU708R6U0zrarw8LQi9T",
      "uri": "https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T",
      "created_at": "2021-10-20T12:07:43Z",
      "description": "development cred for alan@example.com",
      "metadata": "",
      "token": null,
      "acl": []
    },
    {
      "id": "cr_1zlnhoMjlrrV7LIHCvrDLuNCLQH",
      "uri": "https://api.ngrok.com/credentials/cr_1zlnhoMjlrrV7LIHCvrDLuNCLQH",
      "created_at": "2021-10-20T12:07:43Z",
      "description": "for device #132",
      "metadata": "",
      "token": null,
      "acl": [
        "bind:1.tcp.ngrok.io:20002",
        "bind:132.devices.company.com"
      ]
    },
    {
      "id": "cr_1zlnfL0jnrngNBYOtKQOfcSZsZI",
      "uri": "https://api.ngrok.com/credentials/cr_1zlnfL0jnrngNBYOtKQOfcSZsZI",
      "created_at": "2021-10-20T12:07:23Z",
      "description": "credential for \"api-examples-2e53abb0aedc2a82@example.com\"",
      "metadata": "",
      "token": "1zlnfL0jnrngNBYOtKQOfcSZsZI_WBwB79GfNEhF8inhMQkb",
      "acl": []
    }
  ],
  "uri": "https://api.ngrok.com/credentials",
  "next_page_uri": null
}
Fields
credentials Credential

the list of all tunnel credentials on this account

uri string

URI of the tunnel credential list API resource

next_page_uri string

URI of the next page, or null if there is no next page

Credential fields
id string

unique tunnel credential resource identifier

uri string

URI of the tunnel credential API resource

created_at string

timestamp when the tunnel credential was created, RFC 3339 format

description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

token string

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 List<string>

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.

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: 2" \
-d '{"description":"device alpha-2","metadata":"{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}"}' \
https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T
Parameters
id string
description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

acl List<string>

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_1zlnhsWjU708R6U0zrarw8LQi9T",
  "uri": "https://api.ngrok.com/credentials/cr_1zlnhsWjU708R6U0zrarw8LQi9T",
  "created_at": "2021-10-20T12:07:43Z",
  "description": "device alpha-2",
  "metadata": "{\"device_id\": \"d5111ba7-0cc5-4ba3-8398-e6c79e4e89c2\"}",
  "token": null,
  "acl": []
}
Fields
id string

unique tunnel credential resource identifier

uri string

URI of the tunnel credential API resource

created_at string

timestamp when the tunnel credential was created, RFC 3339 format

description string

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

metadata string

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

token string

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 List<string>

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: 2" \
https://api.ngrok.com/tunnel_sessions
Response

Returns a 200 response on success

Example Response
{
  "tunnel_sessions": [
    {
      "agent_version": "3.1000.0-e2e+dirty.7430620e1",
      "credential": {
        "id": "cr_1zlniBaM1ZH0qQjjkRcGjvOtf8K",
        "uri": "https://api.ngrok.com/credentials/cr_1zlniBaM1ZH0qQjjkRcGjvOtf8K"
      },
      "id": "ts_1zlniL4Edkb8D3LKAJ4MPX4mktc",
      "ip": "10.110.2.2",
      "metadata": "",
      "os": "linux",
      "region": "us",
      "started_at": "2021-10-20T12:07:47Z",
      "transport": "ngrok/2",
      "uri": "https://api.ngrok.com/tunnel_sessions/ts_1zlniL4Edkb8D3LKAJ4MPX4mktc"
    },
    {
      "agent_version": "3.1000.0-e2e+dirty.7430620e1",
      "credential": {
        "id": "cr_1zlniPKhLTjDbGzeNBEHSpxd2NR",
        "uri": "https://api.ngrok.com/credentials/cr_1zlniPKhLTjDbGzeNBEHSpxd2NR"
      },
      "id": "ts_1zlniTKnwlxaU2Upu0lxDcml5a8",
      "ip": "10.110.2.2",
      "metadata": "",
      "os": "linux",
      "region": "us",
      "started_at": "2021-10-20T12:07:48Z",
      "transport": "ngrok/2",
      "uri": "https://api.ngrok.com/tunnel_sessions/ts_1zlniTKnwlxaU2Upu0lxDcml5a8"
    }
  ],
  "uri": "https://api.ngrok.com/tunnel_sessions",
  "next_page_uri": null
}
Fields
tunnel_sessions TunnelSession

list of all tunnel sessions on this account

uri string

URI to the API resource of the tunnel session list

next_page_uri string

URI of the next page, or null if there is no next page

TunnelSession fields
agent_version string

version of the ngrok agent that started this ngrok tunnel session

credential Ref

reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session

id string

unique tunnel session resource identifier

ip string

source ip address of the tunnel session

metadata string

arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option

os string

operating system of the host the ngrok agent is running on

region string

the ngrok region identifier in which this tunnel session was started

started_at string

time when the tunnel session first connected to the ngrok servers

transport string

the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh

uri string

URI to the API resource of the tunnel session

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
https://api.ngrok.com/tunnel_sessions/ts_1zlniL4Edkb8D3LKAJ4MPX4mktc
Response

Returns a 200 response on success

Example Response
{
  "agent_version": "3.1000.0-e2e+dirty.7430620e1",
  "credential": {
    "id": "cr_1zlniBaM1ZH0qQjjkRcGjvOtf8K",
    "uri": "https://api.ngrok.com/credentials/cr_1zlniBaM1ZH0qQjjkRcGjvOtf8K"
  },
  "id": "ts_1zlniL4Edkb8D3LKAJ4MPX4mktc",
  "ip": "10.110.2.2",
  "metadata": "",
  "os": "linux",
  "region": "us",
  "started_at": "2021-10-20T12:07:47Z",
  "transport": "ngrok/2",
  "uri": "https://api.ngrok.com/tunnel_sessions/ts_1zlniL4Edkb8D3LKAJ4MPX4mktc"
}
Fields
agent_version string

version of the ngrok agent that started this ngrok tunnel session

credential Ref

reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session

id string

unique tunnel session resource identifier

ip string

source ip address of the tunnel session

metadata string

arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option

os string

operating system of the host the ngrok agent is running on

region string

the ngrok region identifier in which this tunnel session was started

started_at string

time when the tunnel session first connected to the ngrok servers

transport string

the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh

uri string

URI to the API resource of the tunnel session

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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
POST/tunnel_sessions/{id}/restart
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/restart
Parameters
id string

a resource identifier

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
POST/tunnel_sessions/{id}/stop
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/stop
Parameters
id string

a resource identifier

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
POST/tunnel_sessions/{id}/update
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/tunnel_sessions/ts_1vcl4fYZxXY0zNFbpCloylDCG0S/update
Parameters
id string
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: 2" \
https://api.ngrok.com/tunnels
Response

Returns a 200 response on success

Example Response
{
  "tunnels": [
    {
      "id": "tn_1zlniN3unesBf9YDYfdDjSGigcG",
      "public_url": "https://56a352c5d5ac.ngrok.io",
      "started_at": "2021-10-20T12:07:47Z",
      "metadata": "",
      "proto": "https",
      "region": "us",
      "tunnel_session": {
        "id": "ts_1zlniL4Edkb8D3LKAJ4MPX4mktc",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_1zlniL4Edkb8D3LKAJ4MPX4mktc"
      }
    }
  ],
  "uri": "https://api.ngrok.com/tunnels",
  "next_page_uri": null
}
Fields
tunnels Tunnel

the list of all online tunnels on this account

uri string

URI of the tunnels list API resource

next_page_uri string

URI of the next page, or null if there is no next page

Tunnel fields
id string

unique tunnel resource identifier

public_url string

URL of the tunnel’s public endpoint

started_at string

timestamp when the tunnel was initiated in RFC 3339 format

metadata string

user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option In API version 0, this value was instead pulled from the top-level metadata configuration option.

proto string

tunnel protocol. one of http, https, tcp or tls

region string

identifier of tune region where the tunnel is running

tunnel_session Ref

reference object pointing to the tunnel session on which this tunnel was started

Ref fields
id string

a resource identifier

uri string

a uri for locating a resource

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: 2" \
-d '{"provider":"TWILIO","secret":"secret_token"}' \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/webhook_validation
Parameters
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

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 boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/webhook_validation
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "provider": "TWILIO",
  "secret": "secret_token"
}
Fields
enabled boolean

true if the module will be applied to traffic, false to disable. default true if unspecified

provider string

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, SENDGRID, XERO.

secret string

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: 2" \
https://api.ngrok.com/endpoint_configurations/ec_1zlnkSqqYBZ7m2WBsT7N4DoN2Yu/webhook_validation
Response

Returns a 204 response with no body on success