▾ Index
Don't have an ngrok account?

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

The ngrok.com HTTP API

We expose an HTTP API that grants programmatic access to all of ngrok's resources.

This HTTP 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 officially released.

Intended Audience

THIS DOCUMENT ASSUMES YOU HAVE ALREADY READ AND UNDERSTOOD the ngrok documentation. If you have not, you should read the main documentation now. The following content is intended only as a supplement and will not be helpful without the proper context.

Base URL and Authentication

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

The API keys to access the ngrok.com HTTP API are available on your ngrok.com dashboard under the Auth tab. API keys can also be created via the API keys API. 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 <<TOKEN>>" -H "Ngrok-Version: 2" https://api.ngrok.com/

Supported Content Types

Request parameters may be encoded to the API using either application/x-www-form-urlencoded or application/json. Ensure that your client sets the request's Content-Type header appropriately. All responses returned by the API are application/json.

Versioning and API Stability

The 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. Examples of non-breaking changes to the API that will not be opt-in include the following.

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.

Create API Key

Create a new API key. The generated API key can be used to authenticateto 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_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "uri": "https://api.ngrok.com/api_keys/ak_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2021-04-21T23:36:35Z",
  "token": "1rV50mPmItIzKYr2xq3cFxDFH2n_2YdvgqTGLFT38WGWbNxwF"
}
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_1rV50mPmItIzKYr2xq3cFxDFH2n
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_1rV50mPmItIzKYr2xq3cFxDFH2n
Response

Returns a 200 response on success

Example Response
{
  "id": "ak_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "uri": "https://api.ngrok.com/api_keys/ak_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2021-04-21T23:36:35Z",
  "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_1rV50mPmItIzKYr2xq3cFxDFH2n",
      "uri": "https://api.ngrok.com/api_keys/ak_1rV50mPmItIzKYr2xq3cFxDFH2n",
      "description": "ad-hoc dev testing",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2021-04-21T23:36:35Z",
      "token": null
    },
    {
      "id": "ak_1rV4zRtsIg9AwL6r1ENR2TVZZpf",
      "uri": "https://api.ngrok.com/api_keys/ak_1rV4zRtsIg9AwL6r1ENR2TVZZpf",
      "description": "api key for example generation",
      "metadata": "",
      "created_at": "2021-04-21T23:36:24Z",
      "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_1rV50mPmItIzKYr2xq3cFxDFH2n
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_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "uri": "https://api.ngrok.com/api_keys/ak_1rV50mPmItIzKYr2xq3cFxDFH2n",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2021-04-21T23:36:35Z",
  "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_1rV55dwbOBXoa6oMn8dTV0fvq2o",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1rV55dwbOBXoa6oMn8dTV0fvq2o",
  "created_at": "2021-04-21T23:37:14Z",
  "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_1rV55dwbOBXoa6oMn8dTV0fvq2o
Response

Returns a 200 response on success

Example Response
{
  "id": "abrp_1rV55dwbOBXoa6oMn8dTV0fvq2o",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_1rV55dwbOBXoa6oMn8dTV0fvq2o",
  "created_at": "2021-04-21T23:37:14Z",
  "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 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_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "created_at": "2021-04-21T23:38:17Z",
  "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_1rV5Dca4ELSBvqQv2YmoQp4s220
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_1rV5Dca4ELSBvqQv2YmoQp4s220
Response

Returns a 200 response on success

Example Response
{
  "id": "ca_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "created_at": "2021-04-21T23:38:17Z",
  "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_1rV5DZka5Q6SaX2NwY1rKVOVgA1",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV5DZka5Q6SaX2NwY1rKVOVgA1",
      "created_at": "2021-04-21T23:38:17Z",
      "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_1rV5Dca4ELSBvqQv2YmoQp4s220",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV5Dca4ELSBvqQv2YmoQp4s220",
      "created_at": "2021-04-21T23:38:17Z",
      "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_1rV598vJqNfO2QdnQgJPtPquq44",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV598vJqNfO2QdnQgJPtPquq44",
      "created_at": "2021-04-21T23:37:42Z",
      "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_1rV5Dca4ELSBvqQv2YmoQp4s220
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_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV5Dca4ELSBvqQv2YmoQp4s220",
  "created_at": "2021-04-21T23:38:17Z",
  "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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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.
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.
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_1rV504F3NJD5F9CSDUeWRkld2SB",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-04-21T23:36:29Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV504F3NJD5F9CSDUeWRkld2SB",
  "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.
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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_1rV504F3NJD5F9CSDUeWRkld2SB
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_1rV504F3NJD5F9CSDUeWRkld2SB
Response

Returns a 200 response on success

Example Response
{
  "id": "ec_1rV504F3NJD5F9CSDUeWRkld2SB",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-04-21T23:36:29Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV504F3NJD5F9CSDUeWRkld2SB",
  "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_1rV50NAdMzs4UxlKEtqsaCHpGKS",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1rV50NAdMzs4UxlKEtqsaCHpGKS"
      }
    ]
  },
  "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.
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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_1rV504F3NJD5F9CSDUeWRkld2SB",
      "type": "https",
      "description": "app servers",
      "metadata": "",
      "created_at": "2021-04-21T23:36:29Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV504F3NJD5F9CSDUeWRkld2SB",
      "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_1rV4zxf7pC5PFpXAcL2A9VLLeGF",
      "type": "https",
      "description": "web servers",
      "metadata": "",
      "created_at": "2021-04-21T23:36:29Z",
      "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV4zxf7pC5PFpXAcL2A9VLLeGF",
      "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.
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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_1rV50NAdMzs4UxlKEtqsaCHpGKS"]}}' \
https://api.ngrok.com/endpoint_configurations/ec_1rV504F3NJD5F9CSDUeWRkld2SB
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.
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.
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_1rV504F3NJD5F9CSDUeWRkld2SB",
  "type": "https",
  "description": "app servers",
  "metadata": "",
  "created_at": "2021-04-21T23:36:29Z",
  "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV504F3NJD5F9CSDUeWRkld2SB",
  "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_1rV50NAdMzs4UxlKEtqsaCHpGKS",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1rV50NAdMzs4UxlKEtqsaCHpGKS"
      }
    ]
  },
  "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.
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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.
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.
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.
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.
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.
Response

Returns a 200 response on success

Example Response
{
  "id": "ed_1ro7aZHBLfa4vYAeRpweVomDSJa",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2021-04-28T17:24:12Z",
  "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_1ro7aZHBLfa4vYAeRpweVomDSJa"
}
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.
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.
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.
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.

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_1ro7aZHBLfa4vYAeRpweVomDSJa
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_1ro7aZHBLfa4vYAeRpweVomDSJa
Response

Returns a 200 response on success

Example Response
{
  "id": "ed_1ro7aZHBLfa4vYAeRpweVomDSJa",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2021-04-28T17:24:12Z",
  "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_1ro7aZHBLfa4vYAeRpweVomDSJa"
}
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.
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.
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.
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.

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_1ro7YLHYTloEfaH6LDcX2A3z18Q",
      "metadata": "",
      "created_at": "2021-04-28T17:23:54Z",
      "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_1ro7YLHYTloEfaH6LDcX2A3z18Q"
    },
    {
      "id": "ed_1ro7aZHBLfa4vYAeRpweVomDSJa",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2021-04-28T17:24:12Z",
      "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_1ro7aZHBLfa4vYAeRpweVomDSJa"
    },
    {
      "id": "ed_1ro7aG1J2tGT6neX0PHJLTuzQ9E",
      "metadata": "",
      "created_at": "2021-04-28T17:24:09Z",
      "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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"
    }
  ],
  "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.
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.
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.
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.

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_1ro7aZHBLfa4vYAeRpweVomDSJa
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.
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.
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.
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.
Response

Returns a 200 response on success

Example Response
{
  "id": "ed_1ro7aZHBLfa4vYAeRpweVomDSJa",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2021-04-28T17:24:12Z",
  "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_1ro7aZHBLfa4vYAeRpweVomDSJa"
}
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.
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.
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.
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.

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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"],"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_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "uri": "https://api.ngrok.com/event_streams/es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "created_at": "2021-04-28T17:24:09Z",
  "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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"
  ],
  "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_1ro7aBEJQkcfUBNX1r3IBSqjDU8
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_1ro7aBEJQkcfUBNX1r3IBSqjDU8
Response

Returns a 200 response on success

Example Response
{
  "id": "es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "uri": "https://api.ngrok.com/event_streams/es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "created_at": "2021-04-28T17:24:09Z",
  "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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"
  ],
  "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_1ro7YMCmaZu9Tn4cIKoeFvmg8Ce",
      "uri": "https://api.ngrok.com/event_streams/es_1ro7YMCmaZu9Tn4cIKoeFvmg8Ce",
      "created_at": "2021-04-28T17:23:54Z",
      "metadata": "",
      "description": "",
      "fields": [
        "http.request.method",
        "http.response.status_code",
        "conn.client_ip"
      ],
      "event_type": "http_request_complete",
      "destination_ids": [
        "ed_1ro7YLHYTloEfaH6LDcX2A3z18Q"
      ],
      "sampling_rate": 0.1
    },
    {
      "id": "es_1ro7YJvY0atyuqOjbLMsZfe928o",
      "uri": "https://api.ngrok.com/event_streams/es_1ro7YJvY0atyuqOjbLMsZfe928o",
      "created_at": "2021-04-28T17:23:54Z",
      "metadata": "",
      "description": "",
      "fields": [
        "http.request.method",
        "http.response.status_code",
        "conn.client_ip"
      ],
      "event_type": "http_request_complete",
      "destination_ids": [
        "ed_1ro7YLHYTloEfaH6LDcX2A3z18Q"
      ],
      "sampling_rate": 0.1
    },
    {
      "id": "es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
      "uri": "https://api.ngrok.com/event_streams/es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
      "created_at": "2021-04-28T17:24:09Z",
      "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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"
      ],
      "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_1ro7aBEJQkcfUBNX1r3IBSqjDU8
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_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "uri": "https://api.ngrok.com/event_streams/es_1ro7aBEJQkcfUBNX1r3IBSqjDU8",
  "created_at": "2021-04-28T17:24:09Z",
  "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_1ro7aG1J2tGT6neX0PHJLTuzQ9E"
  ],
  "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 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_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "created_at": "2021-04-21T23:36:24Z",
  "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_1rV4zO6CPgrYXRinORa9kQIzN4Z
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_1rV4zO6CPgrYXRinORa9kQIzN4Z
Response

Returns a 200 response on success

Example Response
{
  "id": "ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "created_at": "2021-04-21T23:36:24Z",
  "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_1rV4zSGNWNgXjZBPCIHbpRONB3A",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV4zSGNWNgXjZBPCIHbpRONB3A",
      "created_at": "2021-04-21T23:36:24Z",
      "description": "Developer Environments",
      "metadata": "",
      "action": "allow"
    },
    {
      "id": "ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
      "created_at": "2021-04-21T23:36:24Z",
      "description": "API Outbound Gateway",
      "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_1rV4zO6CPgrYXRinORa9kQIzN4Z
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_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "uri": "https://api.ngrok.com/ip_policies/ipp_1rV4zO6CPgrYXRinORa9kQIzN4Z",
  "created_at": "2021-04-21T23:36:24Z",
  "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_1rV58lgpNclzzHpjzzjfldUfNiC"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV58lgpNclzzHpjzzjfldUfNiC",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV58lgpNclzzHpjzzjfldUfNiC"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/ip_policy
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_1rV58lgpNclzzHpjzzjfldUfNiC",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV58lgpNclzzHpjzzjfldUfNiC"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV56VrAxesFteoj4XZxaaYyvXo"}' \
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_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "created_at": "2021-04-21T23:37:22Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
  }
}
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_1rV56ecFIhdfZ2nG5VZus5PKFtW
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_1rV56ecFIhdfZ2nG5VZus5PKFtW
Response

Returns a 200 response on success

Example Response
{
  "id": "ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "created_at": "2021-04-21T23:37:22Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
  }
}
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_1rV56jFvshOkyVBrKOLNOdd9Jq2",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56jFvshOkyVBrKOLNOdd9Jq2",
      "created_at": "2021-04-21T23:37:22Z",
      "description": "alan laptop",
      "metadata": "",
      "cidr": "2.2.2.2/32",
      "ip_policy": {
        "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
      }
    },
    {
      "id": "ipr_1rV56fKu4NnoTEVfCPSRqE5zRsK",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56fKu4NnoTEVfCPSRqE5zRsK",
      "created_at": "2021-04-21T23:37:22Z",
      "description": "sf office",
      "metadata": "",
      "cidr": "132.2.19.0/24",
      "ip_policy": {
        "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
      }
    },
    {
      "id": "ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
      "created_at": "2021-04-21T23:37:22Z",
      "description": "nyc office",
      "metadata": "",
      "cidr": "212.3.14.0/24",
      "ip_policy": {
        "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
        "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
      }
    }
  ],
  "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_1rV56ecFIhdfZ2nG5VZus5PKFtW
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_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_1rV56ecFIhdfZ2nG5VZus5PKFtW",
  "created_at": "2021-04-21T23:37:22Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_1rV56VrAxesFteoj4XZxaaYyvXo",
    "uri": "https://api.ngrok.com/ip_policies/ipp_1rV56VrAxesFteoj4XZxaaYyvXo"
  }
}
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_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ"]}' \
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 enforce. 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_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "created_at": "2021-04-21T23:38:07Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ"
    }
  ]
}
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 enforce. 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_1rV5CKgSrd3y2fosbXX5GoAhMeR
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_1rV5CKgSrd3y2fosbXX5GoAhMeR
Response

Returns a 200 response on success

Example Response
{
  "id": "ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "created_at": "2021-04-21T23:38:07Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ"
    },
    {
      "id": "ipp_1rV5COeFhKWjXHrEfCGNBXCA4ka",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5COeFhKWjXHrEfCGNBXCA4ka"
    }
  ]
}
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 enforce. 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_1rV5CKgSrd3y2fosbXX5GoAhMeR",
      "uri": "https://api.ngrok.com/ip_restrictions/ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR",
      "created_at": "2021-04-21T23:38:07Z",
      "description": "",
      "metadata": "",
      "enforced": false,
      "type": "dashboard",
      "ip_policies": [
        {
          "id": "ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ",
          "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ"
        }
      ]
    }
  ],
  "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 enforce. 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_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ","ipp_1rV5COeFhKWjXHrEfCGNBXCA4ka"]}' \
https://api.ngrok.com/ip_restrictions/ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR
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 enforce. 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_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_1rV5CKgSrd3y2fosbXX5GoAhMeR",
  "created_at": "2021-04-21T23:38:07Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5CMI1Aw8MiqWtjlQCyDDEWnQ"
    },
    {
      "id": "ipp_1rV5COeFhKWjXHrEfCGNBXCA4ka",
      "uri": "https://api.ngrok.com/ip_policies/ipp_1rV5COeFhKWjXHrEfCGNBXCA4ka"
    }
  ]
}
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 enforce. 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

Create IP Whitelist Entry

Create a new IP whitelist entry that will restrict traffic to all tunnel endpoints on the account.

Request
POST/ip_whitelist
Example Request
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"outbound proxy servers","ip_net":"10.1.1.0/24"}' \
https://api.ngrok.com/ip_whitelist
Parameters
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net string an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
Response

Returns a 200 response on success

Example Response
{
  "id": "wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "created_at": "2021-04-21T23:37:16Z",
  "description": "outbound proxy servers",
  "metadata": "",
  "ip_net": "10.1.1.0/24"
}
Fields
id string unique identifier for this IP whitelist entry
uri string URI of the IP whitelist entry API resource
created_at string timestamp when the IP whitelist entry was created, RFC 3339 format
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net string an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

Delete IP Whitelist Entry

Delete an IP whitelist entry.

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

Returns a 204 response with no body on success

Get IP Whitelist Entry

Get detailed information about an IP whitelist entry by ID.

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

Returns a 200 response on success

Example Response
{
  "id": "wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "created_at": "2021-04-21T23:37:16Z",
  "description": "home office for alan",
  "metadata": "{\"type\": \"home office\", \"employee_name\": \"alan\"}",
  "ip_net": "10.1.1.0/24"
}
Fields
id string unique identifier for this IP whitelist entry
uri string URI of the IP whitelist entry API resource
created_at string timestamp when the IP whitelist entry was created, RFC 3339 format
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net string an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

List IP Whitelist

List all IP whitelist entries on this account

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

Returns a 200 response on success

Example Response
{
  "whitelist": [
    {
      "id": "wl_1rV55uK6IddK1eJWBcopcSqr9jr",
      "uri": "https://api.ngrok.com/ip_whitelist/wl_1rV55uK6IddK1eJWBcopcSqr9jr",
      "created_at": "2021-04-21T23:37:16Z",
      "description": "outbound proxy servers",
      "metadata": "",
      "ip_net": "10.1.1.0/24"
    },
    {
      "id": "wl_1rV55s4NmZ81mUa5zqPetlpngC7",
      "uri": "https://api.ngrok.com/ip_whitelist/wl_1rV55s4NmZ81mUa5zqPetlpngC7",
      "created_at": "2021-04-21T23:37:16Z",
      "description": "office wifi",
      "metadata": "",
      "ip_net": "78.3.12.121/32"
    }
  ],
  "uri": "https://api.ngrok.com/ip_whitelist",
  "next_page_uri": null
}
Fields
whitelist IPWhitelistEntry the list of all IP whitelist entries on this account
uri string URI of the IP whitelist API resource
next_page_uri string URI of the next page, or null if there is no next page
IPWhitelistEntry fields
id string unique identifier for this IP whitelist entry
uri string URI of the IP whitelist entry API resource
created_at string timestamp when the IP whitelist entry was created, RFC 3339 format
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net string an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

Update IP Whitelist Entry

Update attributes of an IP whitelist entry by ID

Request
PATCH/ip_whitelist/{id}
Example Request
curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"home office for alan","metadata":"{\"type\": \"home office\", \"employee_name\": \"alan\"}"}' \
https://api.ngrok.com/ip_whitelist/wl_1rV55uK6IddK1eJWBcopcSqr9jr
Parameters
id string
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
Response

Returns a 200 response on success

Example Response
{
  "id": "wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "uri": "https://api.ngrok.com/ip_whitelist/wl_1rV55uK6IddK1eJWBcopcSqr9jr",
  "created_at": "2021-04-21T23:37:16Z",
  "description": "home office for alan",
  "metadata": "{\"type\": \"home office\", \"employee_name\": \"alan\"}",
  "ip_net": "10.1.1.0/24"
}
Fields
id string unique identifier for this IP whitelist entry
uri string URI of the IP whitelist entry API resource
created_at string timestamp when the IP whitelist entry was created, RFC 3339 format
description string human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata string arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net string an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints

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_1rV5B1c2adFqc5TjufmiyUshtqY","es_1rV5B8xRSKqSpTEtjIZcld3rhIC"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV5B1c2adFqc5TjufmiyUshtqY",
      "uri": "https://api.ngrok.com/event_streams/es_1rV5B1c2adFqc5TjufmiyUshtqY"
    },
    {
      "id": "es_1rV5B8xRSKqSpTEtjIZcld3rhIC",
      "uri": "https://api.ngrok.com/event_streams/es_1rV5B8xRSKqSpTEtjIZcld3rhIC"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/logging
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "event_streams": [
    {
      "id": "es_1rV5B1c2adFqc5TjufmiyUshtqY",
      "uri": "https://api.ngrok.com/event_streams/es_1rV5B1c2adFqc5TjufmiyUshtqY"
    },
    {
      "id": "es_1rV5B8xRSKqSpTEtjIZcld3rhIC",
      "uri": "https://api.ngrok.com/event_streams/es_1rV5B8xRSKqSpTEtjIZcld3rhIC"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV598vJqNfO2QdnQgJPtPquq44"]}' \
https://api.ngrok.com/endpoint_configurations/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV598vJqNfO2QdnQgJPtPquq44",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV598vJqNfO2QdnQgJPtPquq44"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/mutual_tls
Response

Returns a 200 response on success

Example Response
{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_1rV598vJqNfO2QdnQgJPtPquq44",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_1rV598vJqNfO2QdnQgJPtPquq44"
    }
  ]
}
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "created_at": "2021-04-21T23:36:49Z",
  "description": "SSH for device #001",
  "metadata": "",
  "addr": "1.tcp.ngrok.io:20011",
  "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_1rV3SMgGd7NuIB89hzucFK8r8nZ
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_1rV3SMgGd7NuIB89hzucFK8r8nZ
Response

Returns a 200 response on success

Example Response
{
  "id": "ra_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "created_at": "2021-04-21T23:36:49Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20011",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1rV52nyVMhAzUojsbhyljDvazMp",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV52nyVMhAzUojsbhyljDvazMp"
  }
}
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_1rV3SMgGd7NuIB89hzucFK8r8nZ",
      "uri": "https://api.ngrok.com/reserved_addrs/ra_1rV3SMgGd7NuIB89hzucFK8r8nZ",
      "created_at": "2021-04-21T23:36:49Z",
      "description": "SSH for device #001",
      "metadata": "",
      "addr": "1.tcp.ngrok.io:20011",
      "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_1rV52nyVMhAzUojsbhyljDvazMp"}' \
https://api.ngrok.com/reserved_addrs/ra_1rV3SMgGd7NuIB89hzucFK8r8nZ
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_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_1rV3SMgGd7NuIB89hzucFK8r8nZ",
  "created_at": "2021-04-21T23:36:49Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20011",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_1rV52nyVMhAzUojsbhyljDvazMp",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV52nyVMhAzUojsbhyljDvazMp"
  }
}
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_1rV3SMgGd7NuIB89hzucFK8r8nZ/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_1rV51OQetZPK9V6vTWUVy3Onjir"}' \
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_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "created_at": "2021-04-21T23:36:40Z",
  "description": "",
  "metadata": "",
  "domain": "myapp.mydomain.com",
  "region": "us",
  "cname_target": "29flmdbzs.cname.us.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "certificate": {
    "id": "cert_1rV51OQetZPK9V6vTWUVy3Onjir",
    "uri": "https://api.ngrok.com/tls_certificates/cert_1rV51OQetZPK9V6vTWUVy3Onjir"
  },
  "certificate_management_policy": null,
  "certificate_management_status": 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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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
ns_targets ReservedDomainCertNSTarget if present, indicates the dns nameservers that the user must configure to complete the provisioning process of a wildcard certificate
ReservedDomainCertNSTarget fields
zone string the zone that the nameservers need to be applied to
nameservers List<string> the nameservers the user must add

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_1rV51Qr590Jb8MgfiWIxshe0RWs
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_1rV51Qr590Jb8MgfiWIxshe0RWs
Response

Returns a 200 response on success

Example Response
{
  "id": "rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "created_at": "2021-04-21T23:36:40Z",
  "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": "29flmdbzs.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_1rV51lrJYw0LLC6pbNFmjW1KJLE",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV51lrJYw0LLC6pbNFmjW1KJLE"
  },
  "https_endpoint_configuration": {
    "id": "ec_1rV51lUKrRn6BLvLOWq2Ug0nINj",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV51lUKrRn6BLvLOWq2Ug0nINj"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": 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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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
ns_targets ReservedDomainCertNSTarget if present, indicates the dns nameservers that the user must configure to complete the provisioning process of a wildcard certificate
ReservedDomainCertNSTarget fields
zone string the zone that the nameservers need to be applied to
nameservers List<string> the nameservers the user must add

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_1rV51TBbVHrjheFFdfasWnL6E1z",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1rV51TBbVHrjheFFdfasWnL6E1z",
      "created_at": "2021-04-21T23:36:41Z",
      "description": "Device 0001 Dashboard",
      "metadata": "{\"service\": \"dashboard\"}",
      "domain": "manage-0001.app.example.com",
      "region": "us",
      "cname_target": "2y4vzpktb.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": null,
      "certificate_management_policy": null,
      "certificate_management_status": null
    },
    {
      "id": "rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
      "uri": "https://api.ngrok.com/reserved_domains/rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
      "created_at": "2021-04-21T23:36:40Z",
      "description": "",
      "metadata": "",
      "domain": "myapp.mydomain.com",
      "region": "us",
      "cname_target": "29flmdbzs.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": {
        "id": "cert_1rV51OQetZPK9V6vTWUVy3Onjir",
        "uri": "https://api.ngrok.com/tls_certificates/cert_1rV51OQetZPK9V6vTWUVy3Onjir"
      },
      "certificate_management_policy": null,
      "certificate_management_status": 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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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
ns_targets ReservedDomainCertNSTarget if present, indicates the dns nameservers that the user must configure to complete the provisioning process of a wildcard certificate
ReservedDomainCertNSTarget fields
zone string the zone that the nameservers need to be applied to
nameservers List<string> the nameservers the user must add

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_1rV51lrJYw0LLC6pbNFmjW1KJLE","https_endpoint_configuration_id":"ec_1rV51lUKrRn6BLvLOWq2Ug0nINj","certificate_management_policy":{"authority":"letsencrypt"}}' \
https://api.ngrok.com/reserved_domains/rd_1rV51Qr590Jb8MgfiWIxshe0RWs
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_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_1rV51Qr590Jb8MgfiWIxshe0RWs",
  "created_at": "2021-04-21T23:36:40Z",
  "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": "29flmdbzs.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_1rV51lrJYw0LLC6pbNFmjW1KJLE",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV51lrJYw0LLC6pbNFmjW1KJLE"
  },
  "https_endpoint_configuration": {
    "id": "ec_1rV51lUKrRn6BLvLOWq2Ug0nINj",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_1rV51lUKrRn6BLvLOWq2Ug0nINj"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": 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
Ref fields
id string a resource identifier
uri string a uri for locating a resource
Ref fields
id string a resource identifier
uri string a uri for locating a resource
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
ns_targets ReservedDomainCertNSTarget if present, indicates the dns nameservers that the user must configure to complete the provisioning process of a wildcard certificate
ReservedDomainCertNSTarget fields
zone string the zone that the nameservers need to be applied to
nameservers List<string> the nameservers the user must add

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_1rV51Qr590Jb8MgfiWIxshe0RWs/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_1rV51Qr590Jb8MgfiWIxshe0RWs/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_1rV51Qr590Jb8MgfiWIxshe0RWs/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_1rV51Qr590Jb8MgfiWIxshe0RWs/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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.
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_1rV57Kl5MEZblUT9lDlfMG6QWYC",
  "assertion_consumer_service_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/acs",
  "single_logout_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIQRT+PZP7BD/zSwgKtN8pyRDANBgkqhkiG9w0BAQsFADBI\nMUYwRAYDVQQKDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFuL3NhbWwvZWNfMXJW\nNTdLbDVNRVpibFVUOWxEbGZNRzZRV1lDMCAXDTIxMDQyMTIzMzgwMVoYDzIwNTYw\nNDEyMjMzODAxWjBIMUYwRAYDVQQKDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFu\nL3NhbWwvZWNfMXJWNTdLbDVNRVpibFVUOWxEbGZNRzZRV1lDMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr20Jj1vKyta480SCoHjyQlu5baZTVaFveFVL\nd4Ch6Mvby7G+MmKpF/+wgLg5zepEbydlWJRFtLHBXtb/g6+vZJJuNHNUWPRBmTSc\nN+e2pxwQ/ViZG4jEuL6sb4Tv+jNdbcGrDO6orLuPG/6PPyzopjjuE3WxlphQodf6\nd9EUG+O66ucND5NoKsdLX9/mB9kGbOvX1zbmAINZ5Bx+yZssD/uB17DWL9XIK0BZ\nyYtV2AZwc/01D2aLw/eOcHZ0V6GOQKGeqkN81HlYLH2H4GlOXpEyxlDtMvSv+V2a\nu6WHyJWDemn+Np8kgutgsyNw0VyrXIY7f2xbRskjT2MAYPKdlwIDAQABozUwMzAO\nBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDAYDVR0TAQH/BAIw\nADANBgkqhkiG9w0BAQsFAAOCAQEAZRZM+JQwScAI+hrTDNmCAAoR8ZIbeSBLUki3\n4H7JBfdtKrVUx5+8XkcSgO0U5HdTO7mkOi2SeIh0rhVxS+7kCBwh/MwPuRLorT/o\n73qMJ+WhXTMeSUbr/3YnPBoxRfbgz9tUSaGis186YuSHbXKYGoXK2xo0ZN793EtI\nvUw3H4eW6LnoiPs47D2dbdrm/oDPC+TkjoCLdR7dDyldi3w0dfdaX3bPEMtJ0COf\nkktHewGUToTkhEe2QQn/OzxiWU9axmGwfmRBOu4B/dZJ1jt6EusraiLrg/eNR+e9\nMinSvOZU/LBSUggyE0+kC9mTAlQ93LDAUNM9tpaN7B3FMe2Ufg==\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC"
}
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.

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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC",
  "assertion_consumer_service_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/acs",
  "single_logout_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIQRT+PZP7BD/zSwgKtN8pyRDANBgkqhkiG9w0BAQsFADBI\nMUYwRAYDVQQKDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFuL3NhbWwvZWNfMXJW\nNTdLbDVNRVpibFVUOWxEbGZNRzZRV1lDMCAXDTIxMDQyMTIzMzgwMVoYDzIwNTYw\nNDEyMjMzODAxWjBIMUYwRAYDVQQKDD1odHRwczovL2lkcC5uZ3Jvay5jb20ubGFu\nL3NhbWwvZWNfMXJWNTdLbDVNRVpibFVUOWxEbGZNRzZRV1lDMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAr20Jj1vKyta480SCoHjyQlu5baZTVaFveFVL\nd4Ch6Mvby7G+MmKpF/+wgLg5zepEbydlWJRFtLHBXtb/g6+vZJJuNHNUWPRBmTSc\nN+e2pxwQ/ViZG4jEuL6sb4Tv+jNdbcGrDO6orLuPG/6PPyzopjjuE3WxlphQodf6\nd9EUG+O66ucND5NoKsdLX9/mB9kGbOvX1zbmAINZ5Bx+yZssD/uB17DWL9XIK0BZ\nyYtV2AZwc/01D2aLw/eOcHZ0V6GOQKGeqkN81HlYLH2H4GlOXpEyxlDtMvSv+V2a\nu6WHyJWDemn+Np8kgutgsyNw0VyrXIY7f2xbRskjT2MAYPKdlwIDAQABozUwMzAO\nBgNVHQ8BAf8EBAMCB4AwEwYDVR0lBAwwCgYIKwYBBQUHAwEwDAYDVR0TAQH/BAIw\nADANBgkqhkiG9w0BAQsFAAOCAQEAZRZM+JQwScAI+hrTDNmCAAoR8ZIbeSBLUki3\n4H7JBfdtKrVUx5+8XkcSgO0U5HdTO7mkOi2SeIh0rhVxS+7kCBwh/MwPuRLorT/o\n73qMJ+WhXTMeSUbr/3YnPBoxRfbgz9tUSaGis186YuSHbXKYGoXK2xo0ZN793EtI\nvUw3H4eW6LnoiPs47D2dbdrm/oDPC+TkjoCLdR7dDyldi3w0dfdaX3bPEMtJ0COf\nkktHewGUToTkhEe2QQn/OzxiWU9axmGwfmRBOu4B/dZJ1jt6EusraiLrg/eNR+e9\nMinSvOZU/LBSUggyE0+kC9mTAlQ93LDAUNM9tpaN7B3FMe2Ufg==\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.ngrok.com/saml/ec_1rV57Kl5MEZblUT9lDlfMG6QWYC"
}
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.

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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "created_at": "2021-04-21T23:38:32Z",
  "description": "Staging Environment Hosts",
  "metadata": "",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICDx404hGFBUi7mFqNcd1TkrP4MVtf57kJVP3r0h3rSO",
  "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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f
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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f
Response

Returns a 200 response on success

Example Response
{
  "id": "sshca_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "created_at": "2021-04-21T23:38:32Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICDx404hGFBUi7mFqNcd1TkrP4MVtf57kJVP3r0h3rSO",
  "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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
      "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
      "created_at": "2021-04-21T23:38:32Z",
      "description": "Staging Environment Hosts",
      "metadata": "",
      "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICDx404hGFBUi7mFqNcd1TkrP4MVtf57kJVP3r0h3rSO",
      "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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f
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_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_1rV5FT4Uy4JaYbMnSyKS3p0xE4f",
  "created_at": "2021-04-21T23:38:32Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICDx404hGFBUi7mFqNcd1TkrP4MVtf57kJVP3r0h3rSO",
  "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_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "created_at": "2021-04-21T23:37:09Z",
  "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_1rV5504YUNgDKQ3WvFOeotnfgNm
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_1rV5504YUNgDKQ3WvFOeotnfgNm
Response

Returns a 200 response on success

Example Response
{
  "id": "sshcr_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "created_at": "2021-04-21T23:37:09Z",
  "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_1rV5504YUNgDKQ3WvFOeotnfgNm",
      "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1rV5504YUNgDKQ3WvFOeotnfgNm",
      "created_at": "2021-04-21T23:37:09Z",
      "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_1rV5504YUNgDKQ3WvFOeotnfgNm
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_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_1rV5504YUNgDKQ3WvFOeotnfgNm",
  "created_at": "2021-04-21T23:37:09Z",
  "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_1rV5GiTaiBQg8AtJiyiVeNKzYiR","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com","principals":["inconshreveable.com","10.2.42.9"],"valid_until":"2021-07-20T23:38:42Z","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_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "created_at": "2021-04-21T23:38:42Z",
  "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_1rV5GiTaiBQg8AtJiyiVeNKzYiR",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-04-21T23:38:42Z",
  "valid_until": "2021-07-20T23:38:42Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl+i7u7P1mVEWv2Igcf76hXPS2/xnKniDnJZX53xfuTQAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXJWNUduQ0lIZ0tXNE95QklqS1NxcGJhZjA0AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABggLeCAAAAAGD3XoIAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIEpsciWkhlFN7VFWGMkSy1xFNwuZLVh7ZE/uo79NWH8LAAAAUwAAAAtzc2gtZWQyNTUxOQAAAECJHCycrdAf2WNjWGWolP+Y5TlIm5LX4TdRJFeSdUVp0amDg9ZYRltqXy61qGVc43G/unqz35ZzkwJPmVAi/ZQL shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04"
}
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_1rV5GnCIHgKW4OyBIjKSqpbaf04
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_1rV5GnCIHgKW4OyBIjKSqpbaf04
Response

Returns a 200 response on success

Example Response
{
  "id": "shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "created_at": "2021-04-21T23:38:42Z",
  "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_1rV5GiTaiBQg8AtJiyiVeNKzYiR",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-04-21T23:38:42Z",
  "valid_until": "2021-07-20T23:38:42Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl+i7u7P1mVEWv2Igcf76hXPS2/xnKniDnJZX53xfuTQAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXJWNUduQ0lIZ0tXNE95QklqS1NxcGJhZjA0AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABggLeCAAAAAGD3XoIAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIEpsciWkhlFN7VFWGMkSy1xFNwuZLVh7ZE/uo79NWH8LAAAAUwAAAAtzc2gtZWQyNTUxOQAAAECJHCycrdAf2WNjWGWolP+Y5TlIm5LX4TdRJFeSdUVp0amDg9ZYRltqXy61qGVc43G/unqz35ZzkwJPmVAi/ZQL shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04"
}
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_1rV5GnCIHgKW4OyBIjKSqpbaf04",
      "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04",
      "created_at": "2021-04-21T23:38:42Z",
      "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_1rV5GiTaiBQg8AtJiyiVeNKzYiR",
      "principals": [
        "inconshreveable.com",
        "10.2.42.9"
      ],
      "valid_after": "2021-04-21T23:38:42Z",
      "valid_until": "2021-07-20T23:38:42Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl+i7u7P1mVEWv2Igcf76hXPS2/xnKniDnJZX53xfuTQAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXJWNUduQ0lIZ0tXNE95QklqS1NxcGJhZjA0AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABggLeCAAAAAGD3XoIAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIEpsciWkhlFN7VFWGMkSy1xFNwuZLVh7ZE/uo79NWH8LAAAAUwAAAAtzc2gtZWQyNTUxOQAAAECJHCycrdAf2WNjWGWolP+Y5TlIm5LX4TdRJFeSdUVp0amDg9ZYRltqXy61qGVc43G/unqz35ZzkwJPmVAi/ZQL shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04"
    }
  ],
  "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_1rV5GnCIHgKW4OyBIjKSqpbaf04
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_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04",
  "created_at": "2021-04-21T23:38:42Z",
  "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_1rV5GiTaiBQg8AtJiyiVeNKzYiR",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2021-04-21T23:38:42Z",
  "valid_until": "2021-07-20T23:38:42Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl+i7u7P1mVEWv2Igcf76hXPS2/xnKniDnJZX53xfuTQAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMXJWNUduQ0lIZ0tXNE95QklqS1NxcGJhZjA0AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABggLeCAAAAAGD3XoIAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIEpsciWkhlFN7VFWGMkSy1xFNwuZLVh7ZE/uo79NWH8LAAAAUwAAAAtzc2gtZWQyNTUxOQAAAECJHCycrdAf2WNjWGWolP+Y5TlIm5LX4TdRJFeSdUVp0amDg9ZYRltqXy61qGVc43G/unqz35ZzkwJPmVAi/ZQL shcrt_1rV5GnCIHgKW4OyBIjKSqpbaf04"
}
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_1rV5G33U0TV5AFqiEfKcjOi8W4t","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop","principals":["ec2-user","root"],"valid_until":"2021-07-20T23:38:37Z","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_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "created_at": "2021-04-21T23:38:37Z",
  "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_1rV5G33U0TV5AFqiEfKcjOi8W4t",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-04-21T23:38:37Z",
  "valid_until": "2021-07-20T23:38:37Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMQgYZDmRzsM+dcF5rZZM5/xHEFNygLtRKq7Ycsjvk+0AAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXJWNUc4amFyemhJRUVRVHYxd1hSRTFLUlUxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGCAt30AAAAAYPdefQAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAICskbrMYess7OemvQlCikleCUq+2lkxesOd8ivjoWlNCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEA6yhx0v0tzSsQaCQez/qwL8QO+ZLLvKhfmcQ53I0bSYxSaf6G7n8uLThk4OVtq/QJdVaWNcfLrLY0ipITz1RAK sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1"
}
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_1rV5G8jarzhIEEQTv1wXRE1KRU1
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_1rV5G8jarzhIEEQTv1wXRE1KRU1
Response

Returns a 200 response on success

Example Response
{
  "id": "sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "created_at": "2021-04-21T23:38:37Z",
  "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_1rV5G33U0TV5AFqiEfKcjOi8W4t",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-04-21T23:38:37Z",
  "valid_until": "2021-07-20T23:38:37Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMQgYZDmRzsM+dcF5rZZM5/xHEFNygLtRKq7Ycsjvk+0AAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXJWNUc4amFyemhJRUVRVHYxd1hSRTFLUlUxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGCAt30AAAAAYPdefQAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAICskbrMYess7OemvQlCikleCUq+2lkxesOd8ivjoWlNCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEA6yhx0v0tzSsQaCQez/qwL8QO+ZLLvKhfmcQ53I0bSYxSaf6G7n8uLThk4OVtq/QJdVaWNcfLrLY0ipITz1RAK sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1"
}
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_1rV5G8jarzhIEEQTv1wXRE1KRU1",
      "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1",
      "created_at": "2021-04-21T23:38:37Z",
      "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_1rV5G33U0TV5AFqiEfKcjOi8W4t",
      "principals": [
        "ec2-user",
        "root"
      ],
      "critical_options": {},
      "extensions": {
        "permit-pty": "",
        "permit-user-rc": ""
      },
      "valid_after": "2021-04-21T23:38:37Z",
      "valid_until": "2021-07-20T23:38:37Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMQgYZDmRzsM+dcF5rZZM5/xHEFNygLtRKq7Ycsjvk+0AAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXJWNUc4amFyemhJRUVRVHYxd1hSRTFLUlUxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGCAt30AAAAAYPdefQAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAICskbrMYess7OemvQlCikleCUq+2lkxesOd8ivjoWlNCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEA6yhx0v0tzSsQaCQez/qwL8QO+ZLLvKhfmcQ53I0bSYxSaf6G7n8uLThk4OVtq/QJdVaWNcfLrLY0ipITz1RAK sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1"
    }
  ],
  "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_1rV5G8jarzhIEEQTv1wXRE1KRU1
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_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1",
  "created_at": "2021-04-21T23:38:37Z",
  "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_1rV5G33U0TV5AFqiEfKcjOi8W4t",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2021-04-21T23:38:37Z",
  "valid_until": "2021-07-20T23:38:37Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgMQgYZDmRzsM+dcF5rZZM5/xHEFNygLtRKq7Ycsjvk+0AAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMXJWNUc4amFyemhJRUVRVHYxd1hSRTFLUlUxAAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGCAt30AAAAAYPdefQAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAICskbrMYess7OemvQlCikleCUq+2lkxesOd8ivjoWlNCAAAAUwAAAAtzc2gtZWQyNTUxOQAAAEA6yhx0v0tzSsQaCQez/qwL8QO+ZLLvKhfmcQ53I0bSYxSaf6G7n8uLThk4OVtq/QJdVaWNcfLrLY0ipITz1RAK sucrt_1rV5G8jarzhIEEQTv1wXRE1KRU1"
}
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_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "created_at": "2021-04-21T23:38:12Z",
  "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_1rV5D0Ur3PklEGZwRj9m6qCBlCc
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_1rV5D0Ur3PklEGZwRj9m6qCBlCc
Response

Returns a 200 response on success

Example Response
{
  "id": "cert_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "created_at": "2021-04-21T23:38:12Z",
  "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_1rV51OQetZPK9V6vTWUVy3Onjir",
      "uri": "https://api.ngrok.com/tls_certificates/cert_1rV51OQetZPK9V6vTWUVy3Onjir",
      "created_at": "2021-04-21T23:36:40Z",
      "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_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
      "uri": "https://api.ngrok.com/tls_certificates/cert_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
      "created_at": "2021-04-21T23:38:12Z",
      "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_1rV5D0Ur3PklEGZwRj9m6qCBlCc
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_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "uri": "https://api.ngrok.com/tls_certificates/cert_1rV5D0Ur3PklEGZwRj9m6qCBlCc",
  "created_at": "2021-04-21T23:38:12Z",
  "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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "uri": "https://api.ngrok.com/credentials/cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "created_at": "2021-04-21T23:36:55Z",
  "description": "development cred for alan@example.com",
  "metadata": "",
  "token": "1rV53HesDPMw48BJyEO9Zlgz9dd_2VBMEojJaSJd1BZAfSsx7",
  "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_1rV53HesDPMw48BJyEO9Zlgz9dd
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_1rV53HesDPMw48BJyEO9Zlgz9dd
Response

Returns a 200 response on success

Example Response
{
  "id": "cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "uri": "https://api.ngrok.com/credentials/cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "created_at": "2021-04-21T23:36:55Z",
  "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_1rV53L5Cbhpz2SEyPaMuh3Fz4fN",
      "uri": "https://api.ngrok.com/credentials/cr_1rV53L5Cbhpz2SEyPaMuh3Fz4fN",
      "created_at": "2021-04-21T23:36:55Z",
      "description": "for device #132",
      "metadata": "",
      "token": null,
      "acl": [
        "bind:1.tcp.ngrok.io:20002",
        "bind:132.devices.company.com"
      ]
    },
    {
      "id": "cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
      "uri": "https://api.ngrok.com/credentials/cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
      "created_at": "2021-04-21T23:36:55Z",
      "description": "development cred for alan@example.com",
      "metadata": "",
      "token": null,
      "acl": []
    },
    {
      "id": "cr_1rV4zOWU49g2RGwHuBcFWr9rplv",
      "uri": "https://api.ngrok.com/credentials/cr_1rV4zOWU49g2RGwHuBcFWr9rplv",
      "created_at": "2021-04-21T23:36:24Z",
      "description": "credential for \"api-examples-4383c2c31908ce03@example.com\"",
      "metadata": "",
      "token": "1rV4zOWU49g2RGwHuBcFWr9rplv_5wnnrCUAxvQXkRKbYQK6h",
      "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_1rV53HesDPMw48BJyEO9Zlgz9dd
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_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "uri": "https://api.ngrok.com/credentials/cr_1rV53HesDPMw48BJyEO9Zlgz9dd",
  "created_at": "2021-04-21T23:36:55Z",
  "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": "",
      "credential": {
        "id": "cr_1rV54BnShBhgmZvLtZKAOJhI7jR",
        "uri": "https://api.ngrok.com/credentials/cr_1rV54BnShBhgmZvLtZKAOJhI7jR"
      },
      "id": "ts_1rV549gK2e0WnE8Wvk3ab32e98U",
      "ip": "10.42.0.63",
      "metadata": "",
      "os": "linux",
      "region": "us",
      "started_at": "2021-04-21T23:37:02Z",
      "transport": "ngrok/2",
      "uri": "https://api.ngrok.com/tunnel_sessions/ts_1rV549gK2e0WnE8Wvk3ab32e98U"
    }
  ],
  "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_1rV54NuQFrZQOXWW0qR3E6LAKcy
Response

Returns a 200 response on success

Example Response
{
  "agent_version": "",
  "credential": {
    "id": "cr_1rV54Ns9VZahvkhaG7e7Sp0LaXE",
    "uri": "https://api.ngrok.com/credentials/cr_1rV54Ns9VZahvkhaG7e7Sp0LaXE"
  },
  "id": "ts_1rV54NuQFrZQOXWW0qR3E6LAKcy",
  "ip": "10.42.0.63",
  "metadata": "",
  "os": "linux",
  "region": "us",
  "started_at": "2021-04-21T23:37:04Z",
  "transport": "ngrok/2",
  "uri": "https://api.ngrok.com/tunnel_sessions/ts_1rV54NuQFrZQOXWW0qR3E6LAKcy"
}
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/foo/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/foo/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/foo/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_1rV53vIXMKFIfPxXVWbW2sf4OLW",
      "public_url": "http://57ae41e8cfac.ngrok.io",
      "started_at": "2021-04-21T23:37:00Z",
      "metadata": "",
      "proto": "http",
      "region": "us",
      "tunnel_session": {
        "id": "ts_1rV53yu42s8Hb17NxYNmXLDy8zR",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_1rV53yu42s8Hb17NxYNmXLDy8zR"
      }
    },
    {
      "id": "tn_1rV53wi3OtUfY1RbkH2vNsTmLcO",
      "public_url": "https://57ae41e8cfac.ngrok.io",
      "started_at": "2021-04-21T23:37:00Z",
      "metadata": "",
      "proto": "https",
      "region": "us",
      "tunnel_session": {
        "id": "ts_1rV53yu42s8Hb17NxYNmXLDy8zR",
        "uri": "https://api.ngrok.com/tunnel_sessions/ts_1rV53yu42s8Hb17NxYNmXLDy8zR"
      }
    }
  ],
  "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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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.
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.
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/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.
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_1rV57Kl5MEZblUT9lDlfMG6QWYC/webhook_validation
Response

Returns a 204 response with no body on success