ngrok API | ngrok Documentation

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

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

Create API Key

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

Request

POST/api_keys

Example Request

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

Parameters

`description`	string	human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined data of this API key. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response

{
  "id": "ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "uri": "https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2022-04-19T16:01:15Z",
  "token": "281VSAsp9vBP4HDI1LbjLRuzYOI_4GCt7thvvRp13LPKi4CFk"
}

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_281VSAsp9vBP4HDI1LbjLRuzYOI

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_281VSAsp9vBP4HDI1LbjLRuzYOI

Response

Returns a 200 response on success

Example Response

{
  "id": "ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "uri": "https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2022-04-19T16:01:15Z",
  "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_281VS3L0ve1PvWDca4MeFQsFDYo",
      "uri": "https://api.ngrok.com/api_keys/ak_281VS3L0ve1PvWDca4MeFQsFDYo",
      "description": "api key for example generation",
      "metadata": "",
      "created_at": "2022-04-19T16:01:14Z",
      "token": null
    },
    {
      "id": "ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
      "uri": "https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
      "description": "ad-hoc dev testing",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2022-04-19T16:01:15Z",
      "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_281VSAsp9vBP4HDI1LbjLRuzYOI

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_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "uri": "https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI",
  "description": "ad-hoc dev testing",
  "metadata": "{\"environment\":\"dev\", \"owner_id\": 123}",
  "created_at": "2022-04-19T16:01:15Z",
  "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_281VSpi6sapq6HFrXV9oYDcn381",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_281VSpi6sapq6HFrXV9oYDcn381",
  "created_at": "2022-04-19T16:01:21Z",
  "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_281VSpi6sapq6HFrXV9oYDcn381

Response

Returns a 200 response on success

Example Response

{
  "id": "abrp_281VSpi6sapq6HFrXV9oYDcn381",
  "uri": "https://api.ngrok.com/abuse_reports/abrp_281VSpi6sapq6HFrXV9oYDcn381",
  "created_at": "2022-04-19T16:01:21Z",
  "urls": [
    "http://legit-facebook-login.ngrok.io/login"
  ],
  "metadata": "{\"incident_id\":1233122}",
  "status": "PROCESSED",
  "hostnames": [
    {
      "hostname": "legit-facebook-login.ngrok.io",
      "status": "BANNED"
    }
  ]
}

Fields

`id`	string	ID of the abuse report
`uri`	string	URI of the abuse report API resource
`created_at`	string	timestamp that the abuse report record was created in RFC 3339 format
`urls`	List<string>	a list of URLs containing suspected abusive content
`metadata`	string	arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.
`status`	string	Indicates whether ngrok has processed the abuse report. one of `PENDING`, `PROCESSED`, or `PARTIALLY_PROCESSED`
`hostnames`	AbuseReportHostname	an array of hostname statuses related to the report

AbuseReportHostname fields

`hostname`	string	the hostname ngrok has parsed out of one of the reported URLs in this abuse report
`status`	string	indicates what action ngrok has taken against the hostname. one of `PENDING`, `BANNED`, `UNBANNED`, or `IGNORE`

Create Agent Ingress

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

Request

POST/agent_ingresses

Example Request

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

Parameters

`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
`domain`	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.

Response

Returns a 200 response on success

Example Response

{
  "id": "agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "description": "acme devices",
  "metadata": "",
  "domain": "connect.acme.com",
  "ns_targets": [
    "1.kube-dns.kube-system.svc.cluster.local.",
    "2.kube-dns.kube-system.svc.cluster.local.",
    "3.kube-dns.kube-system.svc.cluster.local.",
    "4.kube-dns.kube-system.svc.cluster.local."
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2022-04-19T16:01:23Z"
}

Fields

`id`	string	unique Agent Ingress resource identifier
`uri`	string	URI to the API resource of this Agent ingress
`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
`domain`	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
`ns_targets`	List<string>	a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok
`region_domains`	List<string>	a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions
`created_at`	string	timestamp when the Agent Ingress was created, RFC 3339 format

Delete Agent Ingress

Delete an Agent Ingress by ID

Request

DELETE/agent_ingresses/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0

Response

Returns a 204 response with no body on success

Get Agent Ingress

Get the details of an Agent Ingress by ID.

Request

GET/agent_ingresses/{id}

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "id": "agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "description": "ACME Co. Device Ingress",
  "metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
  "domain": "connect.acme.com",
  "ns_targets": [
    "1.kube-dns.kube-system.svc.cluster.local.",
    "2.kube-dns.kube-system.svc.cluster.local.",
    "3.kube-dns.kube-system.svc.cluster.local.",
    "4.kube-dns.kube-system.svc.cluster.local."
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2022-04-19T16:01:23Z"
}

Fields

`id`	string	unique Agent Ingress resource identifier
`uri`	string	URI to the API resource of this Agent ingress
`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
`domain`	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
`ns_targets`	List<string>	a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok
`region_domains`	List<string>	a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions
`created_at`	string	timestamp when the Agent Ingress was created, RFC 3339 format

List Agent Ingresses

List all Agent Ingresses owned by this account

Request

GET/agent_ingresses

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "ingresses": [
    {
      "id": "agin_281VT7iCDU8U21OBKxXviKHw0q0",
      "uri": "https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0",
      "description": "acme devices",
      "metadata": "",
      "domain": "connect.acme.com",
      "ns_targets": [
        "1.kube-dns.kube-system.svc.cluster.local.",
        "2.kube-dns.kube-system.svc.cluster.local.",
        "3.kube-dns.kube-system.svc.cluster.local.",
        "4.kube-dns.kube-system.svc.cluster.local."
      ],
      "region_domains": [
        "tunnel.us.connect.acme.com"
      ],
      "created_at": "2022-04-19T16:01:23Z"
    }
  ],
  "uri": "https://api.ngrok.com/agent_ingresses",
  "next_page_uri": null
}

Fields

`ingresses`	AgentIngress	the list of Agent Ingresses owned by this account
`uri`	string	URI of the Agent Ingress list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

AgentIngress fields

`id`	string	unique Agent Ingress resource identifier
`uri`	string	URI to the API resource of this Agent ingress
`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
`domain`	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
`ns_targets`	List<string>	a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok
`region_domains`	List<string>	a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions
`created_at`	string	timestamp when the Agent Ingress was created, RFC 3339 format

Update Agent Ingress

Update attributes of an Agent Ingress by ID.

Request

PATCH/agent_ingresses/{id}

Example Request

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

Parameters

`id`	string
`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

Response

Returns a 200 response on success

Example Response

{
  "id": "agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "uri": "https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0",
  "description": "ACME Co. Device Ingress",
  "metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
  "domain": "connect.acme.com",
  "ns_targets": [
    "1.kube-dns.kube-system.svc.cluster.local.",
    "2.kube-dns.kube-system.svc.cluster.local.",
    "3.kube-dns.kube-system.svc.cluster.local.",
    "4.kube-dns.kube-system.svc.cluster.local."
  ],
  "region_domains": [
    "tunnel.us.connect.acme.com"
  ],
  "created_at": "2022-04-19T16:01:23Z"
}

Fields

`id`	string	unique Agent Ingress resource identifier
`uri`	string	URI to the API resource of this Agent ingress
`description`	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
`domain`	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
`ns_targets`	List<string>	a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok
`region_domains`	List<string>	a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions
`created_at`	string	timestamp when the Agent Ingress was created, RFC 3339 format

Create Certificate Authority

Upload a new Certificate Authority

Request

POST/certificate_authorities

Example Request

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

Parameters

`description`	string	human-readable description of this Certificate Authority. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.
`ca_pem`	string	raw PEM of the Certificate Authority

Response

Returns a 200 response on success

Example Response

{
  "id": "ca_281VT17gcUXCLifWhnP2vjjgK8D",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT17gcUXCLifWhnP2vjjgK8D

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_281VT17gcUXCLifWhnP2vjjgK8D

Response

Returns a 200 response on success

Example Response

{
  "id": "ca_281VT17gcUXCLifWhnP2vjjgK8D",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT2mnh6PA3WtOKPh8R5MQwMx",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VT2mnh6PA3WtOKPh8R5MQwMx",
      "created_at": "2022-04-19T16:01:22Z",
      "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_281VT17gcUXCLifWhnP2vjjgK8D",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D",
      "created_at": "2022-04-19T16:01:22Z",
      "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_281VSuoqmi4531iOZ7jKPxUwnfL",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VSuoqmi4531iOZ7jKPxUwnfL",
      "created_at": "2022-04-19T16:01:21Z",
      "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_281VT17gcUXCLifWhnP2vjjgK8D

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_281VT17gcUXCLifWhnP2vjjgK8D",
  "uri": "https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D",
  "created_at": "2022-04-19T16:01:22Z",
  "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 Endpoints

List all active endpoints on the account

Request

GET/endpoints

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints

Response

Returns a 200 response on success

Example Response

{
  "endpoints": [
    {
      "id": "ep_281VSnLqRt28JBuzynQIuwoCwj0",
      "region": "us",
      "created_at": "2022-04-19T16:01:20Z",
      "updated_at": "2022-04-19T16:01:20Z",
      "public_url": "https://9abb9a7aa17c.ngrok.io",
      "proto": "https",
      "hostport": "9abb9a7aa17c.ngrok.io:443",
      "type": "ephemeral",
      "metadata": "",
      "tunnel": {
        "id": "tn_281VSnLqRt28JBuzynQIuwoCwj0",
        "uri": "https://api.ngrok.com/tunnels/tn_281VSnLqRt28JBuzynQIuwoCwj0"
      }
    },
    {
      "id": "ep_281VSm4dePimjSQhoRcfPrK30mT",
      "region": "us",
      "created_at": "2022-04-19T16:01:20Z",
      "updated_at": "2022-04-19T16:01:20Z",
      "public_url": "tls://endpoint-example.com:443",
      "proto": "tls",
      "hostport": "endpoint-example.com:443",
      "type": "edge",
      "metadata": "",
      "domain": {
        "id": "rd_281VSb55rGwqsjze5h7ZR8xUatO",
        "uri": "https://api.ngrok.com/reserved_domains/rd_281VSb55rGwqsjze5h7ZR8xUatO"
      },
      "edge": {
        "id": "edgtls_281VSaU0qZP8KEDTswG6mCYq35W",
        "uri": "https://api.ngrok.com/edges/tls/edgtls_281VSaU0qZP8KEDTswG6mCYq35W"
      }
    }
  ],
  "uri": "https://api.ngrok.com/endpoints",
  "next_page_uri": null
}

Fields

`endpoints`	Endpoint	the list of all active endpoints on this account
`uri`	string	URI of the endpoints list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

Endpoint fields

`id`	string	unique endpoint resource identifier
`region`	string	identifier of the region this endpoint belongs to
`created_at`	string	timestamp when the endpoint was created in RFC 3339 format
`updated_at`	string	timestamp when the endpoint was updated in RFC 3339 format
`public_url`	string	URL of the hostport served by this endpoint
`proto`	string	protocol served by this endpoint. one of `http`, `https`, `tcp`, or `tls`
`hostport`	string	hostport served by this endpoint (hostname:port)
`type`	string	whether the endpoint is `ephemeral` (served directly by an agent-initiated tunnel) or `edge` (served by an edge)
`metadata`	string	user-supplied metadata of the associated tunnel or edge object
`domain`	Ref	the domain reserved for this endpoint
`tcp_addr`	Ref	the address reserved for this endpoint
`tunnel`	Ref	the tunnel serving requests to this endpoint, if this is an ephemeral endpoint
`edge`	Ref	the edge serving requests to this endpoint, if this is an edge endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Get Endpoint

Get the status of an endpoint by ID

Request

GET/endpoints/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints/ep_281VSnLqRt28JBuzynQIuwoCwj0

Response

Returns a 200 response on success

Example Response

{
  "id": "ep_281VSnLqRt28JBuzynQIuwoCwj0",
  "region": "us",
  "created_at": "2022-04-19T16:01:20Z",
  "updated_at": "2022-04-19T16:01:20Z",
  "public_url": "https://9abb9a7aa17c.ngrok.io",
  "proto": "https",
  "hostport": "9abb9a7aa17c.ngrok.io:443",
  "type": "ephemeral",
  "metadata": "",
  "tunnel": {
    "id": "tn_281VSnLqRt28JBuzynQIuwoCwj0",
    "uri": "https://api.ngrok.com/tunnels/tn_281VSnLqRt28JBuzynQIuwoCwj0"
  }
}

Fields

`id`	string	unique endpoint resource identifier
`region`	string	identifier of the region this endpoint belongs to
`created_at`	string	timestamp when the endpoint was created in RFC 3339 format
`updated_at`	string	timestamp when the endpoint was updated in RFC 3339 format
`public_url`	string	URL of the hostport served by this endpoint
`proto`	string	protocol served by this endpoint. one of `http`, `https`, `tcp`, or `tls`
`hostport`	string	hostport served by this endpoint (hostname:port)
`type`	string	whether the endpoint is `ephemeral` (served directly by an agent-initiated tunnel) or `edge` (served by an edge)
`metadata`	string	user-supplied metadata of the associated tunnel or edge object
`domain`	Ref	the domain reserved for this endpoint
`tcp_addr`	Ref	the address reserved for this endpoint
`tunnel`	Ref	the tunnel serving requests to this endpoint, if this is an ephemeral endpoint
`edge`	Ref	the edge serving requests to this endpoint, if this is an edge endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Create Event Destination

Create a new Event Destination. It will not apply to anything until it is associated with an Event Subscription.

Request

POST/event_destinations

Example Request

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

Parameters

`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.

EventTarget parameters

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth parameters

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole parameters

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

AWSCredentials parameters

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Response

Returns a 200 response on success

Example Response

{
  "id": "ed_281VSy3PDTkkZil3Oz6X2ycCjZu",
  "metadata": "{\"environment\":\"dev\"}",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VSy3PDTkkZil3Oz6X2ycCjZu"
}

Fields

`id`	string	Unique identifier for this Event Destination.
`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`created_at`	string	Timestamp when the Event Destination was created, RFC 3339 format.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.
`uri`	string	URI of the Event Destination API resource.

EventTarget fields

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields

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

AWSCredentials fields

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Delete Event Destination

Delete an Event Destination. If the Event Destination is still referenced by an Event Subscription.

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_281VSy3PDTkkZil3Oz6X2ycCjZu

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_281VSy3PDTkkZil3Oz6X2ycCjZu

Response

Returns a 200 response on success

Example Response

{
  "id": "ed_281VSy3PDTkkZil3Oz6X2ycCjZu",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VSy3PDTkkZil3Oz6X2ycCjZu"
}

Fields

`id`	string	Unique identifier for this Event Destination.
`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`created_at`	string	Timestamp when the Event Destination was created, RFC 3339 format.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.
`uri`	string	URI of the Event Destination API resource.

EventTarget fields

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields

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

AWSCredentials fields

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

List Event Destinations

List all Event Destinations on this account.

Request

GET/event_destinations

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "event_destinations": [
    {
      "id": "ed_281VSy3PDTkkZil3Oz6X2ycCjZu",
      "metadata": "{\"environment\":\"dev\"}",
      "created_at": "2022-04-19T16:01:22Z",
      "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_281VSy3PDTkkZil3Oz6X2ycCjZu"
    }
  ],
  "uri": "https://api.ngrok.com/event_destinations",
  "next_page_uri": null
}

Fields

`event_destinations`	EventDestination	The list of all Event Destinations on this account.
`uri`	string	URI of the Event Destinations list API resource.
`next_page_uri`	string	URI of the next page, or null if there is no next page.

EventDestination fields

`id`	string	Unique identifier for this Event Destination.
`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`created_at`	string	Timestamp when the Event Destination was created, RFC 3339 format.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.
`uri`	string	URI of the Event Destination API resource.

EventTarget fields

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields

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

AWSCredentials fields

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Update Event Destination

Update attributes of an Event Destination.

Request

PATCH/event_destinations/{id}

Example Request

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

Parameters

`id`	string	Unique identifier for this Event Destination.
`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.

EventTarget parameters

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth parameters

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole parameters

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

AWSCredentials parameters

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs parameters

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Response

Returns a 200 response on success

Example Response

{
  "id": "ed_281VSy3PDTkkZil3Oz6X2ycCjZu",
  "metadata": "{\"environment\":\"dev\", \"stream\":1}",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VSy3PDTkkZil3Oz6X2ycCjZu"
}

Fields

`id`	string	Unique identifier for this Event Destination.
`metadata`	string	Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.
`created_at`	string	Timestamp when the Event Destination was created, RFC 3339 format.
`description`	string	Human-readable description of the Event Destination. Optional, max 255 bytes.
`format`	string	The output format you would like to serialize events into when sending to their target. Currently the only accepted value is `JSON`.
`target`	EventTarget	An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: `kinesis`, `firehose`, `cloudwatch_logs`, or `s3`.
`uri`	string	URI of the Event Destination API resource.

EventTarget fields

`firehose`	EventTargetFirehose	Configuration used to send events to Amazon Kinesis Data Firehose.
`kinesis`	EventTargetKinesis	Configuration used to send events to Amazon Kinesis.
`cloudwatch_logs`	EventTargetCloudwatchLogs	Configuration used to send events to Amazon CloudWatch Logs.

EventTargetFirehose fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`delivery_stream_arn`	string	An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

AWSAuth fields

`role`	AWSRole	A role for ngrok to assume on your behalf to deposit events into your AWS account.
`creds`	AWSCredentials	Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

AWSRole fields

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

AWSCredentials fields

`aws_access_key_id`	string	The ID portion of an AWS access key.
`aws_secret_access_key`	string	The secret portion of an AWS access key.

EventTargetKinesis fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`stream_arn`	string	An Amazon Resource Name specifying the Kinesis stream to deposit events into.

EventTargetCloudwatchLogs fields

`auth`	AWSAuth	Configuration for how to authenticate into your AWS account. Exactly one of `role` or `creds` should be configured.
`log_group_arn`	string	An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Create Event Source

Add an additional type for which this event subscription will trigger

Request

POST/event_subscriptions/{subscription_id}/sources

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"type":"ip_policy_updated.v0"}' \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources

Parameters

`subscription_id`	string	The unique identifier for the Event Subscription that this Event Source is attached to.
`type`	string	Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response

{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}

Fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Delete Event Source

Remove a type for which this event subscription will trigger

Request

DELETE/event_subscriptions/{subscription_id}/sources/{type}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0

Response

Returns a 204 response with no body on success

Get Event Source

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

Request

GET/event_subscriptions/{subscription_id}/sources/{type}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0

Response

Returns a 200 response on success

Example Response

{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}

Fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

List Event Sources

List the types for which this event subscription will trigger

Request

GET/event_subscriptions/{subscription_id}/sources

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources

Response

Returns a 200 response on success

Example Response

{
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_created.v0"
    },
    {
      "type": "ip_policy_updated.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
    }
  ],
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources"
}

Fields

`sources`	EventSource	The list of all Event Sources for an Event Subscription
`uri`	string	URI of the next page, or null if there is no next page.

EventSource fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Update Event Source

Update the type for which this event subscription will trigger

Request

PATCH/event_subscriptions/{subscription_id}/sources/{type}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{}' \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0

Parameters

`subscription_id`	string	The unique identifier for the Event Subscription that this Event Source is attached to.
`type`	string	Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response

{
  "type": "ip_policy_updated.v0",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}

Fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Create Event Subscription

Create an Event Subscription.

Request

POST/event_subscriptions

Example Request

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

Parameters

`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSourceReplace	Sources containing the types for which this event subscription will trigger
`destination_ids`	List<string>	A list of Event Destination IDs which should be used for this Event Subscription.

EventSourceReplace parameters

`type`	string	Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response

{
  "id": "esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "created_at": "2022-04-19T16:01:22Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "ip policy creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_281VSzqns5VwrsiwF0tP3g1fYX5",
      "uri": "https://api.ngrok.com/event_destinations/ed_281VSzqns5VwrsiwF0tP3g1fYX5"
    }
  ]
}

Fields

`id`	string	Unique identifier for this Event Subscription.
`uri`	string	URI of the Event Subscription API resource.
`created_at`	string	When the Event Subscription was created (RFC 3339 format).
`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSource	Sources containing the types for which this event subscription will trigger
`destinations`	Ref	Destinations to which these events will be sent

EventSource fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete Event Subscription

Delete an Event Subscription.

Request

DELETE/event_subscriptions/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX

Response

Returns a 204 response with no body on success

Get Event Subscription

Get an Event Subscription by ID.

Request

GET/event_subscriptions/{id}

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "id": "esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "created_at": "2022-04-19T16:01:22Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "IP Policy Creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_281VSzqns5VwrsiwF0tP3g1fYX5",
      "uri": "https://api.ngrok.com/event_destinations/ed_281VSzqns5VwrsiwF0tP3g1fYX5"
    }
  ]
}

Fields

`id`	string	Unique identifier for this Event Subscription.
`uri`	string	URI of the Event Subscription API resource.
`created_at`	string	When the Event Subscription was created (RFC 3339 format).
`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSource	Sources containing the types for which this event subscription will trigger
`destinations`	Ref	Destinations to which these events will be sent

EventSource fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

List Event Subscriptions

List this Account’s Event Subscriptions.

Request

GET/event_subscriptions

Example Request

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

Response

Returns a 200 response on success

Example Response

{
  "event_subscriptions": [
    {
      "id": "esb_281VSzYRZ1FetGZzTIb387nk0KX",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX",
      "created_at": "2022-04-19T16:01:22Z",
      "metadata": "{\"environment\": \"staging\"}",
      "description": "ip policy creations",
      "sources": [
        {
          "type": "ip_policy_created.v0",
          "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX/sources/ip_policy_created.v0"
        }
      ],
      "destinations": [
        {
          "id": "ed_281VSzqns5VwrsiwF0tP3g1fYX5",
          "uri": "https://api.ngrok.com/event_destinations/ed_281VSzqns5VwrsiwF0tP3g1fYX5"
        }
      ]
    }
  ],
  "uri": "https://api.ngrok.com/event_subscriptions",
  "next_page_uri": null
}

Fields

`event_subscriptions`	EventSubscription	The list of all Event Subscriptions on this account.
`uri`	string	URI of the Event Subscriptions list API resource.
`next_page_uri`	string	URI of next page, or null if there is no next page.

EventSubscription fields

`id`	string	Unique identifier for this Event Subscription.
`uri`	string	URI of the Event Subscription API resource.
`created_at`	string	When the Event Subscription was created (RFC 3339 format).
`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSource	Sources containing the types for which this event subscription will trigger
`destinations`	Ref	Destinations to which these events will be sent

EventSource fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Update Event Subscription

Update an Event Subscription.

Request

PATCH/event_subscriptions/{id}

Example Request

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

Parameters

`id`	string	Unique identifier for this Event Subscription.
`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSourceReplace	Sources containing the types for which this event subscription will trigger
`destination_ids`	List<string>	A list of Event Destination IDs which should be used for this Event Subscription.

EventSourceReplace parameters

`type`	string	Type of event for which an event subscription will trigger

Response

Returns a 200 response on success

Example Response

{
  "id": "esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX",
  "created_at": "2022-04-19T16:01:22Z",
  "metadata": "{\"environment\": \"staging\"}",
  "description": "IP Policy Creations",
  "sources": [
    {
      "type": "ip_policy_created.v0",
      "uri": "https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX/sources/ip_policy_created.v0"
    }
  ],
  "destinations": [
    {
      "id": "ed_281VSzqns5VwrsiwF0tP3g1fYX5",
      "uri": "https://api.ngrok.com/event_destinations/ed_281VSzqns5VwrsiwF0tP3g1fYX5"
    }
  ]
}

Fields

`id`	string	Unique identifier for this Event Subscription.
`uri`	string	URI of the Event Subscription API resource.
`created_at`	string	When the Event Subscription was created (RFC 3339 format).
`metadata`	string	Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.
`description`	string	Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.
`sources`	EventSource	Sources containing the types for which this event subscription will trigger
`destinations`	Ref	Destinations to which these events will be sent

EventSource fields

`type`	string	Type of event for which an event subscription will trigger
`uri`	string	URI of the Event Source API resource.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Create Failover Backend

Create a new Failover backend

Request

POST/backends/failover

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme failover","metadata":"{\"environment\": \"staging\"}","backends":["bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc"]}' \
https://api.ngrok.com/backends/failover

Parameters

`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "uri": "https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme failover",
  "metadata": "{\"environment\": \"staging\"}",
  "backends": [
    "bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc"
  ]
}

Fields

`id`	string	unique identifier for this Failover backend
`uri`	string	URI of the FailoverBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

Delete Failover Backend

Delete a Failover backend by ID.

Request

DELETE/backends/failover/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq

Response

Returns a 204 response with no body on success

Get Failover Backend

Get detailed information about a Failover backend by ID

Request

GET/backends/failover/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "uri": "https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme failover",
  "metadata": "{\"environment\": \"staging\"}",
  "backends": [
    "bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc"
  ]
}

Fields

`id`	string	unique identifier for this Failover backend
`uri`	string	URI of the FailoverBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

List Failover Backends

List all Failover backends on this account

Request

GET/backends/failover

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover

Response

Returns a 200 response on success

Example Response

{
  "backends": [
    {
      "id": "bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
      "uri": "https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
      "created_at": "2022-04-19T16:01:23Z",
      "description": "acme failover",
      "metadata": "{\"environment\": \"staging\"}",
      "backends": [
        "bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc"
      ]
    }
  ],
  "uri": "https://api.ngrok.com/backends/failover",
  "next_page_uri": null
}

Fields

`backends`	FailoverBackend	the list of all Failover backends on this account
`uri`	string	URI of the Failover backends list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

FailoverBackend fields

`id`	string	unique identifier for this Failover backend
`uri`	string	URI of the FailoverBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

Update Failover Backend

Update Failover backend by ID

Request

PATCH/backends/failover/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq

Parameters

`id`	string
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "uri": "https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme failover",
  "metadata": "{\"environment\": \"production\"}",
  "backends": []
}

Fields

`id`	string	unique identifier for this Failover backend
`uri`	string	URI of the FailoverBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`backends`	List<string>	the ids of the child backends in order

Create HTTP Response Backend

Request

POST/backends/http_response

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme http response","metadata":"{\"environment\": \"staging\"}","body":"I'm a teapot","headers":{"Content-Type":"text/plain"},"status_code":418}' \
https://api.ngrok.com/backends/http_response

Parameters

`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme http response",
  "metadata": "{\"environment\": \"staging\"}",
  "body": "I'm a teapot",
  "headers": {
    "content-type": "text/plain"
  },
  "status_code": 418
}

Fields

`id`	string
`uri`	string	URI of the HTTPResponseBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

Delete HTTP Response Backend

Request

DELETE/backends/http_response/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD

Response

Returns a 204 response with no body on success

Get HTTP Response Backend

Request

GET/backends/http_response/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme http response",
  "metadata": "{\"environment\": \"staging\"}",
  "body": "I'm a teapot",
  "headers": {
    "content-type": "text/plain"
  },
  "status_code": 418
}

Fields

`id`	string
`uri`	string	URI of the HTTPResponseBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

List HTTP Response Backends

Request

GET/backends/http_response

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response

Response

Returns a 200 response on success

Example Response

{
  "backends": [
    {
      "id": "bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
      "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
      "created_at": "2022-04-19T16:01:23Z",
      "description": "acme http response",
      "metadata": "{\"environment\": \"staging\"}",
      "body": "I'm a teapot",
      "headers": {
        "content-type": "text/plain"
      },
      "status_code": 418
    },
    {
      "id": "bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc",
      "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VT4v8O6v9WX2yjIKidVuFWNc",
      "created_at": "2022-04-19T16:01:23Z",
      "description": "",
      "metadata": "",
      "body": "one",
      "headers": null,
      "status_code": 200
    },
    {
      "id": "bkdhr_281VSdmzh7sDOqD0SKztgPXP141",
      "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VSdmzh7sDOqD0SKztgPXP141",
      "created_at": "2022-04-19T16:01:19Z",
      "description": "",
      "metadata": "",
      "body": "one",
      "headers": null,
      "status_code": 200
    }
  ],
  "uri": "https://api.ngrok.com/backends/http_response",
  "next_page_uri": null
}

Fields

`backends`	HTTPResponseBackend
`uri`	string
`next_page_uri`	string

HTTPResponseBackend fields

`id`	string
`uri`	string	URI of the HTTPResponseBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

Update HTTP Response Backend

Request

PATCH/backends/http_response/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD

Parameters

`id`	string
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

Response

Returns a 200 response on success

Example Response

{
  "id": "bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD",
  "created_at": "2022-04-19T16:01:23Z",
  "description": "acme http response",
  "metadata": "{\"environment\": \"production\"}",
  "body": "I'm a teapot",
  "headers": {
    "content-type": "text/plain"
  },
  "status_code": 418
}

Fields

`id`	string
`uri`	string	URI of the HTTPResponseBackend API resource
`created_at`	string	timestamp when the backend was created, RFC 3339 format
`description`	string	human-readable description of this backend. Optional
`metadata`	string	arbitrary user-defined machine-readable data of this backend. Optional
`body`	string	body to return as fixed content
`headers`	Map<string, string>	headers to return
`status_code`	int32	status code to return

Replace HTTPS Edge Mutual TLS Module

Request

PUT/edges/https/{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_281VTOvsYutJN79tshryTFd8YcT"]}' \
https://api.ngrok.com/edges/https/edghts_281VTOIZuRn6l6t3RbPs90EA84V/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 presented by the initiator of the TLS connection

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_281VTOvsYutJN79tshryTFd8YcT",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VTOvsYutJN79tshryTFd8YcT"
    }
  ]
}

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 HTTPS Edge Mutual TLS Module

Request

GET/edges/https/{id}/mutual_tls

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTOIZuRn6l6t3RbPs90EA84V/mutual_tls

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_281VTOvsYutJN79tshryTFd8YcT",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VTOvsYutJN79tshryTFd8YcT"
    }
  ]
}

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 HTTPS Edge Mutual TLS Module

Request

DELETE/edges/https/{id}/mutual_tls

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTOIZuRn6l6t3RbPs90EA84V/mutual_tls

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Backend Module

Request

PUT/edges/https/{edge_id}/routes/{id}/backend

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"backend_id":"bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL"}' \
https://api.ngrok.com/edges/https/edghts_281VTBTkVvIKR5LBqGWQHYq102f/routes/edghtsrt_281VTAkONRZIfHtyT0jU4xjMghW/backend

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Get HTTPS Edge Route Backend Module

Request

GET/edges/https/{edge_id}/routes/{id}/backend

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTBTkVvIKR5LBqGWQHYq102f/routes/edghtsrt_281VTAkONRZIfHtyT0jU4xjMghW/backend

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete HTTPS Edge Route Backend Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/backend

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTBTkVvIKR5LBqGWQHYq102f/routes/edghtsrt_281VTAkONRZIfHtyT0jU4xjMghW/backend

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Circuit Breaker Module

Request

PUT/edges/https/{edge_id}/routes/{id}/circuit_breaker

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"tripped_duration":120,"rolling_window":300,"num_buckets":5,"volume_threshold":20,"error_threshold_percentage":0.2}' \
https://api.ngrok.com/edges/https/edghts_281VTAlbmmCtnz8aIQ4rZ9Watd0/routes/edghtsrt_281VTF1H2vBrsGv4xB7mQHSjCe6/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 HTTPS Edge Route Circuit Breaker Module

Request

GET/edges/https/{edge_id}/routes/{id}/circuit_breaker

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTAlbmmCtnz8aIQ4rZ9Watd0/routes/edghtsrt_281VTF1H2vBrsGv4xB7mQHSjCe6/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 HTTPS Edge Route Circuit Breaker Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/circuit_breaker

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTAlbmmCtnz8aIQ4rZ9Watd0/routes/edghtsrt_281VTF1H2vBrsGv4xB7mQHSjCe6/circuit_breaker

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Compression Module

Request

PUT/edges/https/{edge_id}/routes/{id}/compression

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true}' \
https://api.ngrok.com/edges/https/edghts_281VTICZn3JxyemtDzdDponcV1i/routes/edghtsrt_281VTFoeCkjSj68dhokLNbeea4O/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": true
}

Fields

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

Get HTTPS Edge Route Compression Module

Request

GET/edges/https/{edge_id}/routes/{id}/compression

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTICZn3JxyemtDzdDponcV1i/routes/edghtsrt_281VTFoeCkjSj68dhokLNbeea4O/compression

Response

Returns a 200 response on success

Example Response

{
  "enabled": true
}

Fields

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

Delete HTTPS Edge Route Compression Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/compression

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTICZn3JxyemtDzdDponcV1i/routes/edghtsrt_281VTFoeCkjSj68dhokLNbeea4O/compression

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route IP Restriction Module

Request

PUT/edges/https/{edge_id}/routes/{id}/ip_restriction

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"ip_policy_ids":["ipp_281VTFiwLfnUYsZXlRtcRje52JD","ipp_281VTH2Bo2hFnVQ7Tyu4mart1cf"]}' \
https://api.ngrok.com/edges/https/edghts_281VTI3xOHmd0aG61mAvGP62Z6o/routes/edghtsrt_281VTHX9DkHujAr6IyXV6o2fYum/ip_restriction

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_281VTFiwLfnUYsZXlRtcRje52JD",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTFiwLfnUYsZXlRtcRje52JD"
    },
    {
      "id": "ipp_281VTH2Bo2hFnVQ7Tyu4mart1cf",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTH2Bo2hFnVQ7Tyu4mart1cf"
    }
  ]
}

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 HTTPS Edge Route IP Restriction Module

Request

GET/edges/https/{edge_id}/routes/{id}/ip_restriction

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTI3xOHmd0aG61mAvGP62Z6o/routes/edghtsrt_281VTHX9DkHujAr6IyXV6o2fYum/ip_restriction

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_281VTFiwLfnUYsZXlRtcRje52JD",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTFiwLfnUYsZXlRtcRje52JD"
    },
    {
      "id": "ipp_281VTH2Bo2hFnVQ7Tyu4mart1cf",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTH2Bo2hFnVQ7Tyu4mart1cf"
    }
  ]
}

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 HTTPS Edge Route IP Restriction Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/ip_restriction

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTI3xOHmd0aG61mAvGP62Z6o/routes/edghtsrt_281VTHX9DkHujAr6IyXV6o2fYum/ip_restriction

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route OAuth Module

Request

PUT/edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"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"]}}}' \
https://api.ngrok.com/edges/https/edghts_281VTEQGEkE0JRZMAQyfOhLX9U2/routes/edghtsrt_281VTDhQz1Pn2Q6vtJMpo3jNhbm/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": false,
  "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 HTTPS Edge Route OAuth Module

Request

GET/edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTEQGEkE0JRZMAQyfOhLX9U2/routes/edghtsrt_281VTDhQz1Pn2Q6vtJMpo3jNhbm/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": false,
  "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 HTTPS Edge Route OAuth Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTEQGEkE0JRZMAQyfOhLX9U2/routes/edghtsrt_281VTDhQz1Pn2Q6vtJMpo3jNhbm/oauth

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route OIDC Module

Request

PUT/edges/https/{edge_id}/routes/{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/edges/https/edghts_281VTJwvbSCgr00EB0BsF3AZxDh/routes/edghtsrt_281VTGcUEoT0QK6I4tWaIQV7duR/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 HTTPS Edge Route OIDC Module

Request

GET/edges/https/{edge_id}/routes/{id}/oidc

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTJwvbSCgr00EB0BsF3AZxDh/routes/edghtsrt_281VTGcUEoT0QK6I4tWaIQV7duR/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 HTTPS Edge Route OIDC Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/oidc

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTJwvbSCgr00EB0BsF3AZxDh/routes/edghtsrt_281VTGcUEoT0QK6I4tWaIQV7duR/oidc

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Request Headers Module

Request

PUT/edges/https/{edge_id}/routes/{id}/request_headers

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"add":{"x-frontend":"ngrok"},"remove":["cache-control"]}' \
https://api.ngrok.com/edges/https/edghts_281VTFOBEJOuQ5dXQc8v8uRkwh9/routes/edghtsrt_281VTESQEq3fmk37WsXyk4wcpC1/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-frontend": "ngrok"
  },
  "remove": [
    "cache-control"
  ]
}

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 HTTPS Edge Route Request Headers Module

Request

GET/edges/https/{edge_id}/routes/{id}/request_headers

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTFOBEJOuQ5dXQc8v8uRkwh9/routes/edghtsrt_281VTESQEq3fmk37WsXyk4wcpC1/request_headers

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "add": {
    "x-frontend": "ngrok"
  },
  "remove": [
    "cache-control"
  ]
}

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 HTTPS Edge Route Request Headers Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/request_headers

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTFOBEJOuQ5dXQc8v8uRkwh9/routes/edghtsrt_281VTESQEq3fmk37WsXyk4wcpC1/request_headers

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Response Headers Module

Request

PUT/edges/https/{edge_id}/routes/{id}/response_headers

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"add":{"Content-Security-Policy":"script-src 'self'","X-Frame-Options":"DENY"}}' \
https://api.ngrok.com/edges/https/edghts_281VTDMn17IPi6TcwF9U2h06VJG/routes/edghtsrt_281VTDDL1TZPcbooRrnkrSgAwBw/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": {
    "content-security-policy": "script-src 'self'",
    "x-frame-options": "DENY"
  },
  "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 HTTPS Edge Route Response Headers Module

Request

GET/edges/https/{edge_id}/routes/{id}/response_headers

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTDMn17IPi6TcwF9U2h06VJG/routes/edghtsrt_281VTDDL1TZPcbooRrnkrSgAwBw/response_headers

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "add": {
    "content-security-policy": "script-src 'self'",
    "x-frame-options": "DENY"
  },
  "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 HTTPS Edge Route Response Headers Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/response_headers

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTDMn17IPi6TcwF9U2h06VJG/routes/edghtsrt_281VTDDL1TZPcbooRrnkrSgAwBw/response_headers

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route SAML Module

Request

PUT/edges/https/{edge_id}/routes/{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/edges/https/edghts_281VTNsKKnioB1QNHXsRoeWCPPc/routes/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/saml

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "options_passthrough": false,
  "cookie_prefix": "",
  "inactivity_timeout": 0,
  "maximum_duration": 0,
  "idp_metadata_url": "",
  "idp_metadata": "\n\u003cEntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" validUntil=\"2020-09-14T12:53:23.691Z\" cacheDuration=\"PT1M\" entityID=\"http://127.0.0.1:12345/metadata\"\u003e\u003cIDPSSODescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" protocolSupportEnumeration=\"urn:oasis:names:tc:SAML:2.0:protocol\"\u003e\u003cNameIDFormat\u003eurn:oasis:names:tc:SAML:2.0:nameid-format:transient\u003c/NameIDFormat\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003cSingleSignOnService Binding=\"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\" Location=\"http://127.0.0.1:12345/sso\"\u003e\u003c/SingleSignOnService\u003e\u003c/IDPSSODescriptor\u003e\u003c/EntityDescriptor\u003e\n",
  "force_authn": false,
  "allow_idp_initiated": true,
  "authorized_groups": [],
  "entity_id": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE",
  "assertion_consumer_service_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/acs",
  "single_logout_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIEBDCCAuygAwIBAgIRAO8Qc5nv2WIuBG/Xt0JmKMQwDQYJKoZIhvcNAQELBQAw\ngaAxTjBMBgNVBAoMRWh0dHBzOi8vaWRwLmxvY2FsLW5ncm9rLmNvbS9zYW1sL2Vk\nZ2h0c3J0XzI4MVZUTzJhdmJTcG54Yk5CeGNJOXk0Y2JCRTFOMEwGA1UEAwxFaHR0\ncHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3NhbWwvZWRnaHRzcnRfMjgxVlRPMmF2\nYlNwbnhiTkJ4Y0k5eTRjYkJFMCAXDTIyMDQxOTE2MDEyNVoYDzIwNTcwNDEwMTYw\nMTI1WjCBoDFOMEwGA1UECgxFaHR0cHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3Nh\nbWwvZWRnaHRzcnRfMjgxVlRPMmF2YlNwbnhiTkJ4Y0k5eTRjYkJFMU4wTAYDVQQD\nDEVodHRwczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2FtbC9lZGdodHNydF8yODFW\nVE8yYXZiU3BueGJOQnhjSTl5NGNiQkUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw\nggEKAoIBAQDJExlOgv4FTjqnaqMnBORl6rGw5oqW0/Vi4kgGrj/NHHIHhtvIm8p3\npTJwpJCiwVEGUC8yV0NEBD/xHatE1YFO0UuwqoH82W8RAsSUFjHyGRHgp/5eQ8P+\ncz5C/4BQaEPU+mfEzRSnfRWxAWc7eHKI/t89p5+RKpXj2rtLg46Noqa2zWPOvqmV\nFZPPpammR7uueGDhj+S/XOqFSM2DqQkKAIIyalRFUDi5jkv+rRrFZ7vkdkfgTkP4\nZAPXlJIWMgoOhB5Mev3YsGDcQU2ACmlwEIuoTGcaH4ZB0kHZ4cEqLAnKHX2SSKKh\n2xisHBiq/ZZobzKhzDdRwEbT7DG0T5w3AgMBAAGjNTAzMA4GA1UdDwEB/wQEAwIH\ngDATBgNVHSUEDDAKBggrBgEFBQcDATAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEB\nCwUAA4IBAQBYXOe1pMcIIcDd6HGzyW9ssFqwww3aU8ZYkfjN1GM3+3yfQjuyUUFR\nmNntZlMaKDvqM+AVGiRvXjneOhvEzdPv4Dbv5jnqyZd6Nc7AByjvYPi1kTZPiEQ+\nN+Pp7gA+D6jPMqi/fBOSdjE0KXYuV/q2dF9FoNlYIiGCs9ylNbeaBUodjEbBUdMr\nJ2/KYBN7iUa5N9W81zqmAgsdO/KrdyznulSQbtm5JtkAW3Y0hkPM5nDDc98GkNKP\n0bESO2fKOciZo+uE7i/7KWxqun4pDPkFDOZ9jm7webZFfvFAgNU9i2s1Ku0JVvdl\n0PbxzZiMpYB2WUT7a26fyBU9sexklM6v\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE",
  "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Get HTTPS Edge Route SAML Module

Request

GET/edges/https/{edge_id}/routes/{id}/saml

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNsKKnioB1QNHXsRoeWCPPc/routes/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/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.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE",
  "assertion_consumer_service_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/acs",
  "single_logout_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/slo",
  "request_signing_certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIEBDCCAuygAwIBAgIRAO8Qc5nv2WIuBG/Xt0JmKMQwDQYJKoZIhvcNAQELBQAw\ngaAxTjBMBgNVBAoMRWh0dHBzOi8vaWRwLmxvY2FsLW5ncm9rLmNvbS9zYW1sL2Vk\nZ2h0c3J0XzI4MVZUTzJhdmJTcG54Yk5CeGNJOXk0Y2JCRTFOMEwGA1UEAwxFaHR0\ncHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3NhbWwvZWRnaHRzcnRfMjgxVlRPMmF2\nYlNwbnhiTkJ4Y0k5eTRjYkJFMCAXDTIyMDQxOTE2MDEyNVoYDzIwNTcwNDEwMTYw\nMTI1WjCBoDFOMEwGA1UECgxFaHR0cHM6Ly9pZHAubG9jYWwtbmdyb2suY29tL3Nh\nbWwvZWRnaHRzcnRfMjgxVlRPMmF2YlNwbnhiTkJ4Y0k5eTRjYkJFMU4wTAYDVQQD\nDEVodHRwczovL2lkcC5sb2NhbC1uZ3Jvay5jb20vc2FtbC9lZGdodHNydF8yODFW\nVE8yYXZiU3BueGJOQnhjSTl5NGNiQkUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw\nggEKAoIBAQDJExlOgv4FTjqnaqMnBORl6rGw5oqW0/Vi4kgGrj/NHHIHhtvIm8p3\npTJwpJCiwVEGUC8yV0NEBD/xHatE1YFO0UuwqoH82W8RAsSUFjHyGRHgp/5eQ8P+\ncz5C/4BQaEPU+mfEzRSnfRWxAWc7eHKI/t89p5+RKpXj2rtLg46Noqa2zWPOvqmV\nFZPPpammR7uueGDhj+S/XOqFSM2DqQkKAIIyalRFUDi5jkv+rRrFZ7vkdkfgTkP4\nZAPXlJIWMgoOhB5Mev3YsGDcQU2ACmlwEIuoTGcaH4ZB0kHZ4cEqLAnKHX2SSKKh\n2xisHBiq/ZZobzKhzDdRwEbT7DG0T5w3AgMBAAGjNTAzMA4GA1UdDwEB/wQEAwIH\ngDATBgNVHSUEDDAKBggrBgEFBQcDATAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEB\nCwUAA4IBAQBYXOe1pMcIIcDd6HGzyW9ssFqwww3aU8ZYkfjN1GM3+3yfQjuyUUFR\nmNntZlMaKDvqM+AVGiRvXjneOhvEzdPv4Dbv5jnqyZd6Nc7AByjvYPi1kTZPiEQ+\nN+Pp7gA+D6jPMqi/fBOSdjE0KXYuV/q2dF9FoNlYIiGCs9ylNbeaBUodjEbBUdMr\nJ2/KYBN7iUa5N9W81zqmAgsdO/KrdyznulSQbtm5JtkAW3Y0hkPM5nDDc98GkNKP\n0bESO2fKOciZo+uE7i/7KWxqun4pDPkFDOZ9jm7webZFfvFAgNU9i2s1Ku0JVvdl\n0PbxzZiMpYB2WUT7a26fyBU9sexklM6v\n-----END CERTIFICATE-----\n",
  "metadata_url": "https://idp.local-ngrok.com/saml/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE",
  "nameid_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Delete HTTPS Edge Route SAML Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/saml

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNsKKnioB1QNHXsRoeWCPPc/routes/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/saml

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Webhook Verification Module

Request

PUT/edges/https/{edge_id}/routes/{id}/webhook_verification

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"provider":"TWILIO","secret":"secret_token"}' \
https://api.ngrok.com/edges/https/edghts_281VTO7BArEgS26LC5E0slWMt3g/routes/edghtsrt_281VTQ51icCsDPz6T41bNMJXF0Q/webhook_verification

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`secret`	string	a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "provider": "TWILIO",
  "secret": "secret_token"
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`secret`	string	a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Get HTTPS Edge Route Webhook Verification Module

Request

GET/edges/https/{edge_id}/routes/{id}/webhook_verification

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTO7BArEgS26LC5E0slWMt3g/routes/edghtsrt_281VTQ51icCsDPz6T41bNMJXF0Q/webhook_verification

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "provider": "TWILIO",
  "secret": "secret_token"
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`secret`	string	a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Delete HTTPS Edge Route Webhook Verification Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/webhook_verification

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTO7BArEgS26LC5E0slWMt3g/routes/edghtsrt_281VTQ51icCsDPz6T41bNMJXF0Q/webhook_verification

Response

Returns a 204 response with no body on success

Replace HTTPS Edge Route Websocket TCP Converter Module

Request

PUT/edges/https/{edge_id}/routes/{id}/websocket_tcp_converter

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true}' \
https://api.ngrok.com/edges/https/edghts_281VTQs5x5F20R1aPPCqneRwNgT/routes/edghtsrt_281VTRd1jjHokPCxDz0x3CtQbVW/websocket_tcp_converter

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": true
}

Fields

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

Get HTTPS Edge Route Websocket TCP Converter Module

Request

GET/edges/https/{edge_id}/routes/{id}/websocket_tcp_converter

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTQs5x5F20R1aPPCqneRwNgT/routes/edghtsrt_281VTRd1jjHokPCxDz0x3CtQbVW/websocket_tcp_converter

Response

Returns a 200 response on success

Example Response

{
  "enabled": true
}

Fields

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

Delete HTTPS Edge Route Websocket TCP Converter Module

Request

DELETE/edges/https/{edge_id}/routes/{id}/websocket_tcp_converter

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTQs5x5F20R1aPPCqneRwNgT/routes/edghtsrt_281VTRd1jjHokPCxDz0x3CtQbVW/websocket_tcp_converter

Response

Returns a 204 response with no body on success

Create HTTPS Edge Route

Create an HTTPS Edge Route

Request

POST/edges/https/{edge_id}/routes

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"match_type":"path_prefix","match":"/","description":"acme edge route","metadata":"{\"environment\": \"staging\"}"}' \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes

Parameters

`edge_id`	string	unique identifier of this edge
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackendMutate	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicyMutate	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAMLMutate	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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

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

EndpointWebhookValidation parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAMLMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter 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

{
  "edge_id": "edghts_281VT6kmMfszIxuhVrmwbOPyXxq",
  "id": "edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "created_at": "2022-04-19T16:01:23Z",
  "match_type": "path_prefix",
  "match": "/",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "description": "acme edge route",
  "metadata": "{\"environment\": \"staging\"}",
  "backend": null,
  "ip_restriction": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": null,
  "response_headers": null,
  "webhook_verification": null,
  "oauth": null,
  "saml": null,
  "oidc": null,
  "websocket_tcp_converter": null
}

Fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Get HTTPS Edge Route

Get an HTTPS Edge Route by ID

Request

GET/edges/https/{edge_id}/routes/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm

Response

Returns a 200 response on success

Example Response

{
  "edge_id": "edghts_281VT6kmMfszIxuhVrmwbOPyXxq",
  "id": "edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "created_at": "2022-04-19T16:01:23Z",
  "match_type": "path_prefix",
  "match": "/",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "description": "acme edge route",
  "metadata": "{\"environment\": \"staging\"}",
  "backend": null,
  "ip_restriction": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": null,
  "response_headers": null,
  "webhook_verification": null,
  "oauth": null,
  "saml": null,
  "oidc": null,
  "websocket_tcp_converter": null
}

Fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Update HTTPS Edge Route

Updates an HTTPS Edge Route by ID. 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/edges/https/{edge_id}/routes/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm

Parameters

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackendMutate	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicyMutate	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAMLMutate	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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

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

EndpointWebhookValidation parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAMLMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter 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

{
  "edge_id": "edghts_281VT6kmMfszIxuhVrmwbOPyXxq",
  "id": "edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "created_at": "2022-04-19T16:01:23Z",
  "match_type": "path_prefix",
  "match": "/",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm",
  "description": "",
  "metadata": "{\"environment\": \"production\"}",
  "backend": null,
  "ip_restriction": null,
  "circuit_breaker": null,
  "compression": null,
  "request_headers": null,
  "response_headers": null,
  "webhook_verification": null,
  "oauth": null,
  "saml": null,
  "oidc": null,
  "websocket_tcp_converter": null
}

Fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Delete HTTPS Edge Route

Delete an HTTPS Edge Route by ID

Request

DELETE/edges/https/{edge_id}/routes/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm

Response

Returns a 204 response with no body on success

Replace HTTPS Edge TLS Termination Module

Request

PUT/edges/https/{id}/tls_termination

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"min_version":"1.3"}' \
https://api.ngrok.com/edges/https/edghts_281VTNCqUW9Q6u0uH0gDA9PRExk/tls_termination

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`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.3"
}

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 HTTPS Edge TLS Termination Module

Request

GET/edges/https/{id}/tls_termination

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNCqUW9Q6u0uH0gDA9PRExk/tls_termination

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "terminate_at": "edge",
  "min_version": "1.3"
}

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 HTTPS Edge TLS Termination Module

Request

DELETE/edges/https/{id}/tls_termination

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNCqUW9Q6u0uH0gDA9PRExk/tls_termination

Response

Returns a 204 response with no body on success

Create HTTPS Edge

Create an HTTPS Edge

Request

POST/edges/https

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme https edge","metadata":"{\"environment\": \"staging\"}","hostports":["example.com:443"]}' \
https://api.ngrok.com/edges/https

Parameters

`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLSMutate	edge modules
`tls_termination`	EndpointTLSTerminationAtEdge

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 presented by the initiator of the TLS connection

EndpointTLSTerminationAtEdge parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`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

{
  "id": "edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "description": "acme https edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:23Z",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "hostports": [
    "example.com:443"
  ],
  "mutual_tls": null,
  "tls_termination": null,
  "routes": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLS	edge modules
`tls_termination`	EndpointTLSTermination
`routes`	HTTPSEdgeRoute	routes

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`.

HTTPSEdgeRoute fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Get HTTPS Edge

Get an HTTPS Edge by ID

Request

GET/edges/https/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7

Response

Returns a 200 response on success

Example Response

{
  "id": "edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "description": "acme https edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:23Z",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "hostports": [
    "example.com:443"
  ],
  "mutual_tls": null,
  "tls_termination": null,
  "routes": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLS	edge modules
`tls_termination`	EndpointTLSTermination
`routes`	HTTPSEdgeRoute	routes

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`.

HTTPSEdgeRoute fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

List HTTPS Edges

Returns a list of all HTTPS Edges on this account

Request

GET/edges/https

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https

Response

Returns a 200 response on success

Example Response

{
  "https_edges": [
    {
      "id": "edghts_281VT89MbGew8qSxfYqb4CdXGH7",
      "description": "acme https edge",
      "metadata": "{\"environment\": \"staging\"}",
      "created_at": "2022-04-19T16:01:23Z",
      "uri": "https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7",
      "hostports": [
        "example.com:443"
      ],
      "mutual_tls": null,
      "tls_termination": null,
      "routes": null
    }
  ],
  "uri": "https://api.ngrok.com/edges/https",
  "next_page_uri": null
}

Fields

`https_edges`	HTTPSEdge	the list of all HTTPS Edges on this account
`uri`	string	URI of the HTTPS Edge list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

HTTPSEdge fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLS	edge modules
`tls_termination`	EndpointTLSTermination
`routes`	HTTPSEdgeRoute	routes

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`.

HTTPSEdgeRoute fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Update HTTPS Edge

Updates an HTTPS Edge by ID. 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/edges/https/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7

Parameters

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLSMutate	edge modules
`tls_termination`	EndpointTLSTerminationAtEdge

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 presented by the initiator of the TLS connection

EndpointTLSTerminationAtEdge parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`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

{
  "id": "edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "description": "acme https edge",
  "metadata": "{\"environment\": \"production\"}",
  "created_at": "2022-04-19T16:01:23Z",
  "uri": "https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7",
  "hostports": [
    "example.com:443"
  ],
  "mutual_tls": null,
  "tls_termination": null,
  "routes": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`mutual_tls`	EndpointMutualTLS	edge modules
`tls_termination`	EndpointTLSTermination
`routes`	HTTPSEdgeRoute	routes

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`.

HTTPSEdgeRoute fields

`edge_id`	string	unique identifier of this edge
`id`	string	unique identifier of this edge route
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`match_type`	string	Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.
`match`	string	Route selector: “/blog” or “example.com” or “example.com/blog”
`uri`	string	URI of the edge API resource
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`backend`	EndpointBackend	backend module configuration or `null`
`ip_restriction`	EndpointIPPolicy	ip restriction module configuration or `null`
`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`
`webhook_verification`	EndpointWebhookValidation	webhook verification module configuration or `null`
`oauth`	EndpointOAuth	oauth module configuration or `null`
`saml`	EndpointSAML	saml module configuration or `null`
`oidc`	EndpointOIDC	oidc module configuration or `null`
`websocket_tcp_converter`	EndpointWebsocketTCPConverter	websocket to tcp adapter configuration or `null`

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

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

EndpointWebhookValidation fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`provider`	string	a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: `SLACK`, `SNS`, `STRIPE`, `GITHUB`, `TWILIO`, `SHOPIFY`, `GITLAB`, `INTERCOM`, `SENDGRID`, `XERO`, `PAGERDUTY`.
`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

EndpointSAML fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`idp_metadata`	string	The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
`force_authn`	boolean	If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
`allow_idp_initiated`	boolean	If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the `RelayState` parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
`authorized_groups`	List<string>	If present, only users who are a member of one of the listed groups may access the target endpoint.
`entity_id`	string	The SP Entity’s unique ID. This always takes the form of a URL. In ngrok’s implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
`assertion_consumer_service_url`	string	The public URL of the SP’s Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
`single_logout_url`	string	The public URL of the SP’s Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
`request_signing_certificate_pem`	string	PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP’s configuration if it is supported.
`metadata_url`	string	A public URL where the SP’s metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
`nameid_format`	string	Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent` will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`options_passthrough`	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
`cookie_prefix`	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’
`inactivity_timeout`	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
`maximum_duration`	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
`issuer`	string	URL of the OIDC “OpenID provider”. This is the base URL used for discovery.
`client_id`	string	The OIDC app’s client ID and OIDC audience.
`client_secret`	string	The OIDC app’s client secret.
`scopes`	List<string>	The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

Delete HTTPS Edge

Delete an HTTPS Edge by ID

Request

DELETE/edges/https/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7

Response

Returns a 204 response with no body on success

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"}' \
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.

Response

Returns a 200 response on success

Example Response

{
  "id": "ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "uri": "https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "API Outbound Gateway",
  "metadata": ""
}

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.

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_281VSBiy4r0HL5yaeQwrfDBrAOB

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_281VSBiy4r0HL5yaeQwrfDBrAOB

Response

Returns a 200 response on success

Example Response

{
  "id": "ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "uri": "https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}"
}

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.

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_281VSBiy4r0HL5yaeQwrfDBrAOB",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
      "created_at": "2022-04-19T16:01:15Z",
      "description": "API Outbound Gateway",
      "metadata": ""
    },
    {
      "id": "ipp_281VS7XoBV4va8EFP5lnBtAnajp",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VS7XoBV4va8EFP5lnBtAnajp",
      "created_at": "2022-04-19T16:01:15Z",
      "description": "Developer Environments",
      "metadata": ""
    }
  ],
  "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.

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_281VSBiy4r0HL5yaeQwrfDBrAOB

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_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "uri": "https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "API Outbound Gateway",
  "metadata": "metadata={\"pod-id\": \"b3d9c464-4f48-4783-a741-d7d7d5db310f\"}"
}

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.

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_281VSvEDNBSfHOUHMu0Kk8FSYrI","action":"allow"}' \
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
`action`	string	the action to apply to the policy rule, either `allow` or `deny`

Response

Returns a 200 response on success

Example Response

{
  "id": "ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "created_at": "2022-04-19T16:01:21Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.14.0/24",
  "ip_policy": {
    "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
    "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
  },
  "action": "allow"
}

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
`action`	string	the action to apply to the policy rule, either `allow` or `deny`

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_281VSx5DhHmBReHTT6sUbgs0vgZ

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_281VSx5DhHmBReHTT6sUbgs0vgZ

Response

Returns a 200 response on success

Example Response

{
  "id": "ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "created_at": "2022-04-19T16:01:21Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
    "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
  },
  "action": "allow"
}

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
`action`	string	the action to apply to the policy rule, either `allow` or `deny`

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_281VSx5DhHmBReHTT6sUbgs0vgZ",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
      "created_at": "2022-04-19T16:01:21Z",
      "description": "nyc office",
      "metadata": "",
      "cidr": "212.3.14.0/24",
      "ip_policy": {
        "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
        "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
      },
      "action": "allow"
    },
    {
      "id": "ipr_281VStGjPILan0ZIHngvxqfQKlJ",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VStGjPILan0ZIHngvxqfQKlJ",
      "created_at": "2022-04-19T16:01:21Z",
      "description": "alan laptop",
      "metadata": "",
      "cidr": "2.2.2.2/32",
      "ip_policy": {
        "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
        "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
      },
      "action": "allow"
    },
    {
      "id": "ipr_281VSsbfs7JTe5Sh6pV1uNUXemr",
      "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VSsbfs7JTe5Sh6pV1uNUXemr",
      "created_at": "2022-04-19T16:01:21Z",
      "description": "sf office",
      "metadata": "",
      "cidr": "132.2.19.0/24",
      "ip_policy": {
        "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
        "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
      },
      "action": "allow"
    }
  ],
  "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
`action`	string	the action to apply to the policy rule, either `allow` or `deny`

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_281VSx5DhHmBReHTT6sUbgs0vgZ

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_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "uri": "https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ",
  "created_at": "2022-04-19T16:01:21Z",
  "description": "nyc office",
  "metadata": "",
  "cidr": "212.3.15.0/24",
  "ip_policy": {
    "id": "ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI",
    "uri": "https://api.ngrok.com/ip_policies/ipp_281VSvEDNBSfHOUHMu0Kk8FSYrI"
  },
  "action": "allow"
}

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
`action`	string	the action to apply to the policy rule, either `allow` or `deny`

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_281VSy7y3pOFSIoblcULymlUaBH"]}' \
https://api.ngrok.com/ip_restrictions

Parameters

`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`type`	string	the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: `dashboard`, `api`, `agent`, and `endpoints`
`ip_policy_ids`	List<string>	the set of IP policy identifiers that are used to enforce the restriction

Response

Returns a 200 response on success

Example Response

{
  "id": "ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_281VSy7y3pOFSIoblcULymlUaBH",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSy7y3pOFSIoblcULymlUaBH"
    }
  ]
}

Fields

`id`	string	unique identifier for this IP restriction
`uri`	string	URI of the IP restriction API resource
`created_at`	string	timestamp when the IP restriction was created, RFC 3339 format
`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`type`	string	the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: `dashboard`, `api`, `agent`, and `endpoints`
`ip_policies`	Ref	the set of IP policies that are used to enforce the restriction

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete IP Restriction

Delete an IP restriction

Request

DELETE/ip_restrictions/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt

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_281VSyVE0wH5VxK8PT991OpcaUt

Response

Returns a 200 response on success

Example Response

{
  "id": "ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_281VSy7y3pOFSIoblcULymlUaBH",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSy7y3pOFSIoblcULymlUaBH"
    },
    {
      "id": "ipp_281VSxAtrfYmUkWROFEMUXBEook",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSxAtrfYmUkWROFEMUXBEook"
    }
  ]
}

Fields

`id`	string	unique identifier for this IP restriction
`uri`	string	URI of the IP restriction API resource
`created_at`	string	timestamp when the IP restriction was created, RFC 3339 format
`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`type`	string	the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: `dashboard`, `api`, `agent`, and `endpoints`
`ip_policies`	Ref	the set of IP policies that are used to enforce the restriction

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

List IP Restrictions

List all IP restrictions on this account

Request

GET/ip_restrictions

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions

Response

Returns a 200 response on success

Example Response

{
  "ip_restrictions": [
    {
      "id": "ipx_281VSyVE0wH5VxK8PT991OpcaUt",
      "uri": "https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt",
      "created_at": "2022-04-19T16:01:22Z",
      "description": "",
      "metadata": "",
      "enforced": false,
      "type": "dashboard",
      "ip_policies": [
        {
          "id": "ipp_281VSy7y3pOFSIoblcULymlUaBH",
          "uri": "https://api.ngrok.com/ip_policies/ipp_281VSy7y3pOFSIoblcULymlUaBH"
        }
      ]
    }
  ],
  "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 restrictions list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

IPRestriction fields

`id`	string	unique identifier for this IP restriction
`uri`	string	URI of the IP restriction API resource
`created_at`	string	timestamp when the IP restriction was created, RFC 3339 format
`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`type`	string	the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: `dashboard`, `api`, `agent`, and `endpoints`
`ip_policies`	Ref	the set of IP policies that are used to enforce the restriction

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Update IP Restriction

Update attributes of an IP restriction by ID

Request

PATCH/ip_restrictions/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"ip_policy_ids":["ipp_281VSy7y3pOFSIoblcULymlUaBH","ipp_281VSxAtrfYmUkWROFEMUXBEook"]}' \
https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt

Parameters

`id`	string
`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`ip_policy_ids`	List<string>	the set of IP policy identifiers that are used to enforce the restriction

Response

Returns a 200 response on success

Example Response

{
  "id": "ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "uri": "https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "",
  "metadata": "",
  "enforced": false,
  "type": "dashboard",
  "ip_policies": [
    {
      "id": "ipp_281VSy7y3pOFSIoblcULymlUaBH",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSy7y3pOFSIoblcULymlUaBH"
    },
    {
      "id": "ipp_281VSxAtrfYmUkWROFEMUXBEook",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VSxAtrfYmUkWROFEMUXBEook"
    }
  ]
}

Fields

`id`	string	unique identifier for this IP restriction
`uri`	string	URI of the IP restriction API resource
`created_at`	string	timestamp when the IP restriction was created, RFC 3339 format
`description`	string	human-readable description of this IP restriction. optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
`enforced`	boolean	true if the IP restriction will be enforced. if false, only warnings will be issued
`type`	string	the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: `dashboard`, `api`, `agent`, and `endpoints`
`ip_policies`	Ref	the set of IP policies that are used to enforce the restriction

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

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)

Response

Returns a 200 response on success

Example Response

{
  "id": "ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "SSH for device #001",
  "metadata": "",
  "addr": "1.tcp.ngrok.io:20020",
  "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)

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_27zPQF5dYWaDnNkX9H7cumNLSZX

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_27zPQF5dYWaDnNkX9H7cumNLSZX

Response

Returns a 200 response on success

Example Response

{
  "id": "ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20020",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_281VS5OySblu5hI7mH9XC9ygC85",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS5OySblu5hI7mH9XC9ygC85"
  }
}

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)

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_27zPQF5dYWaDnNkX9H7cumNLSZX",
      "uri": "https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
      "created_at": "2022-04-19T16:01:15Z",
      "description": "SSH for device #001",
      "metadata": "",
      "addr": "1.tcp.ngrok.io:20020",
      "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)

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_281VS5OySblu5hI7mH9XC9ygC85"}' \
https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX

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.

Response

Returns a 200 response on success

Example Response

{
  "id": "ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "uri": "https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "SSH for device #001",
  "metadata": "{\"proto\": \"ssh\"}",
  "addr": "1.tcp.ngrok.io:20020",
  "region": "us",
  "endpoint_configuration": {
    "id": "ec_281VS5OySblu5hI7mH9XC9ygC85",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS5OySblu5hI7mH9XC9ygC85"
  }
}

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)

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_281VS9tZw5Z1WxZTXn2SOUJUtVk"}' \
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.
`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_281VS7M93ynIx1xAz19JU7m9pWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs",
  "created_at": "2022-04-19T16:01:15Z",
  "description": "",
  "metadata": "",
  "domain": "myapp.mydomain.com",
  "region": "us",
  "cname_target": "83ixdbr.cname.us.ngrok.io",
  "http_endpoint_configuration": null,
  "https_endpoint_configuration": null,
  "certificate": {
    "id": "cert_281VS9tZw5Z1WxZTXn2SOUJUtVk",
    "uri": "https://api.ngrok.com/tls_certificates/cert_281VS9tZw5Z1WxZTXn2SOUJUtVk"
  },
  "certificate_management_policy": null,
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}

Fields

`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
`cname_target`	string	DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
`certificate`	Ref	object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

ReservedDomainCertPolicy fields

`authority`	string	certificate authority to request certificates from. The only supported value is letsencrypt.
`private_key_type`	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields

`renews_at`	string	timestamp when the next renewal will be requested, RFC 3339 format
`provisioning_job`	ReservedDomainCertJob	status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields

`error_code`	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
`msg`	string	a message describing the current status or error
`started_at`	string	timestamp when the provisioning job started, RFC 3339 format
`retries_at`	string	timestamp when the provisioning job will be retried

Delete Reserved Domain

Delete a reserved domain.

Request

DELETE/reserved_domains/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs

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_281VS7M93ynIx1xAz19JU7m9pWs

Response

Returns a 200 response on success

Example Response

{
  "id": "rd_281VS7M93ynIx1xAz19JU7m9pWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs",
  "created_at": "2022-04-19T16:01:15Z",
  "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": "83ixdbr.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_281VS7UkzTHc9wJpyXcbvfN7Z2W",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS7UkzTHc9wJpyXcbvfN7Z2W"
  },
  "https_endpoint_configuration": {
    "id": "ec_281VS8rl3diVq38GU4vGuP1FoaT",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS8rl3diVq38GU4vGuP1FoaT"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}

Fields

`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
`cname_target`	string	DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
`certificate`	Ref	object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

ReservedDomainCertPolicy fields

`authority`	string	certificate authority to request certificates from. The only supported value is letsencrypt.
`private_key_type`	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields

`renews_at`	string	timestamp when the next renewal will be requested, RFC 3339 format
`provisioning_job`	ReservedDomainCertJob	status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields

`error_code`	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
`msg`	string	a message describing the current status or error
`started_at`	string	timestamp when the provisioning job started, RFC 3339 format
`retries_at`	string	timestamp when the provisioning job will be retried

List Reserved Domains

List all reserved domains on this account.

Request

GET/reserved_domains

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains

Response

Returns a 200 response on success

Example Response

{
  "reserved_domains": [
    {
      "id": "rd_281VS7M93ynIx1xAz19JU7m9pWs",
      "uri": "https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs",
      "created_at": "2022-04-19T16:01:15Z",
      "description": "",
      "metadata": "",
      "domain": "myapp.mydomain.com",
      "region": "us",
      "cname_target": "83ixdbr.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": {
        "id": "cert_281VS9tZw5Z1WxZTXn2SOUJUtVk",
        "uri": "https://api.ngrok.com/tls_certificates/cert_281VS9tZw5Z1WxZTXn2SOUJUtVk"
      },
      "certificate_management_policy": null,
      "certificate_management_status": null,
      "acme_challenge_cname_target": null
    },
    {
      "id": "rd_281VS5LwFqj1zgaMUJp0MPc84vF",
      "uri": "https://api.ngrok.com/reserved_domains/rd_281VS5LwFqj1zgaMUJp0MPc84vF",
      "created_at": "2022-04-19T16:01:15Z",
      "description": "Device 0001 Dashboard",
      "metadata": "{\"service\": \"dashboard\"}",
      "domain": "manage-0001.app.example.com",
      "region": "us",
      "cname_target": "2vraixg46.cname.us.ngrok.io",
      "http_endpoint_configuration": null,
      "https_endpoint_configuration": null,
      "certificate": null,
      "certificate_management_policy": {
        "authority": "letsencrypt",
        "private_key_type": "ecdsa"
      },
      "certificate_management_status": {
        "renews_at": null,
        "provisioning_job": {
          "error_code": null,
          "msg": "Managed certificate provisioning in progress.",
          "started_at": "2022-04-19T16:01:15Z",
          "retries_at": null
        }
      },
      "acme_challenge_cname_target": null
    }
  ],
  "uri": "https://api.ngrok.com/reserved_domains",
  "next_page_uri": null
}

Fields

`reserved_domains`	ReservedDomain	the list of all reserved domains on this account
`uri`	string	URI of the reserved domain list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

ReservedDomain fields

`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
`cname_target`	string	DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
`certificate`	Ref	object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

ReservedDomainCertPolicy fields

`authority`	string	certificate authority to request certificates from. The only supported value is letsencrypt.
`private_key_type`	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields

`renews_at`	string	timestamp when the next renewal will be requested, RFC 3339 format
`provisioning_job`	ReservedDomainCertJob	status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields

`error_code`	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
`msg`	string	a message describing the current status or error
`started_at`	string	timestamp when the provisioning job started, RFC 3339 format
`retries_at`	string	timestamp when the provisioning job will be retried

Update Reserved Domain

Update the attributes of a reserved domain.

Request

PATCH/reserved_domains/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"point-of-sale new york #302","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}","http_endpoint_configuration_id":"ec_281VS7UkzTHc9wJpyXcbvfN7Z2W","https_endpoint_configuration_id":"ec_281VS8rl3diVq38GU4vGuP1FoaT","certificate_management_policy":{"authority":"letsencrypt"}}' \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs

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.
`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_281VS7M93ynIx1xAz19JU7m9pWs",
  "uri": "https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs",
  "created_at": "2022-04-19T16:01:15Z",
  "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": "83ixdbr.cname.us.ngrok.io",
  "http_endpoint_configuration": {
    "id": "ec_281VS7UkzTHc9wJpyXcbvfN7Z2W",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS7UkzTHc9wJpyXcbvfN7Z2W"
  },
  "https_endpoint_configuration": {
    "id": "ec_281VS8rl3diVq38GU4vGuP1FoaT",
    "uri": "https://api.ngrok.com/endpoint_configurations/ec_281VS8rl3diVq38GU4vGuP1FoaT"
  },
  "certificate": null,
  "certificate_management_policy": {
    "authority": "letsencrypt",
    "private_key_type": "ecdsa"
  },
  "certificate_management_status": null,
  "acme_challenge_cname_target": null
}

Fields

`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
`cname_target`	string	DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
`certificate`	Ref	object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

ReservedDomainCertPolicy fields

`authority`	string	certificate authority to request certificates from. The only supported value is letsencrypt.
`private_key_type`	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

ReservedDomainCertStatus fields

`renews_at`	string	timestamp when the next renewal will be requested, RFC 3339 format
`provisioning_job`	ReservedDomainCertJob	status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

ReservedDomainCertJob fields

`error_code`	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
`msg`	string	a message describing the current status or error
`started_at`	string	timestamp when the provisioning job started, RFC 3339 format
`retries_at`	string	timestamp when the provisioning job will be retried

Detach Certificate Management Policy from Reserved Domain

Detach the certificate management policy attached to a reserved domain.

Request

DELETE/reserved_domains/{id}/certificate_management_policy

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs/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_281VS7M93ynIx1xAz19JU7m9pWs/certificate

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_281VSyZ5CbmEEF3wsJLu84DK05d",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "Staging Environment Hosts",
  "metadata": "",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICS5K5RhXJUgdUuwdr95vtYI1Tuds/x0xDOnDXhP3986",
  "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_281VSyZ5CbmEEF3wsJLu84DK05d

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_281VSyZ5CbmEEF3wsJLu84DK05d

Response

Returns a 200 response on success

Example Response

{
  "id": "sshca_281VSyZ5CbmEEF3wsJLu84DK05d",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICS5K5RhXJUgdUuwdr95vtYI1Tuds/x0xDOnDXhP3986",
  "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_281VSyZ5CbmEEF3wsJLu84DK05d",
      "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d",
      "created_at": "2022-04-19T16:01:22Z",
      "description": "Staging Environment Hosts",
      "metadata": "",
      "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICS5K5RhXJUgdUuwdr95vtYI1Tuds/x0xDOnDXhP3986",
      "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_281VSyZ5CbmEEF3wsJLu84DK05d

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_281VSyZ5CbmEEF3wsJLu84DK05d",
  "uri": "https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d",
  "created_at": "2022-04-19T16:01:22Z",
  "description": "Staging Environment Hosts",
  "metadata": "{\"region\": \"us-east-1\"}",
  "public_key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICS5K5RhXJUgdUuwdr95vtYI1Tuds/x0xDOnDXhP3986",
  "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_281VSqzhNBtReJAzZkuS1EhqqC5",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5",
  "created_at": "2022-04-19T16:01:21Z",
  "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_281VSqzhNBtReJAzZkuS1EhqqC5

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_281VSqzhNBtReJAzZkuS1EhqqC5

Response

Returns a 200 response on success

Example Response

{
  "id": "sshcr_281VSqzhNBtReJAzZkuS1EhqqC5",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5",
  "created_at": "2022-04-19T16:01:21Z",
  "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_281VSqzhNBtReJAzZkuS1EhqqC5",
      "uri": "https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5",
      "created_at": "2022-04-19T16:01:21Z",
      "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_281VSqzhNBtReJAzZkuS1EhqqC5

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_281VSqzhNBtReJAzZkuS1EhqqC5",
  "uri": "https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5",
  "created_at": "2022-04-19T16:01:21Z",
  "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_281VT1ifntUvZ72li9WAGmucxOF","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+Cgk= inconshreveable.com","principals":["inconshreveable.com","10.2.42.9"],"valid_until":"2022-07-18T11:01:22-05:00","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_281VT63521pxlmlwyzPtVwf6lBy",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy",
  "created_at": "2022-04-19T16:01:23Z",
  "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_281VT1ifntUvZ72li9WAGmucxOF",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2022-04-19T16:01:23Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl1WUDNZfsY689785xZZajV5YyaHsDD/yQk4H9laIaJ4AAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMjgxVlQ2MzUyMXB4bG1sd3l6UHRWd2Y2bEJ5AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABiXtzTAAAAAGLVg9IAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIOdNfhjh41qFmuV8DICvY1bn6HywrT3UzfWf8VtGKeH3AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDVKMaoe/v431f5XkUZk32gd/1bvku/TRL+NCJr4uioy9XcuAINA9xBHaPi60mS49ODwzrGnfxA67h/PDhAREwJ shcrt_281VT63521pxlmlwyzPtVwf6lBy"
}

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_281VT63521pxlmlwyzPtVwf6lBy

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_281VT63521pxlmlwyzPtVwf6lBy

Response

Returns a 200 response on success

Example Response

{
  "id": "shcrt_281VT63521pxlmlwyzPtVwf6lBy",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy",
  "created_at": "2022-04-19T16:01:23Z",
  "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_281VT1ifntUvZ72li9WAGmucxOF",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2022-04-19T16:01:23Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl1WUDNZfsY689785xZZajV5YyaHsDD/yQk4H9laIaJ4AAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMjgxVlQ2MzUyMXB4bG1sd3l6UHRWd2Y2bEJ5AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABiXtzTAAAAAGLVg9IAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIOdNfhjh41qFmuV8DICvY1bn6HywrT3UzfWf8VtGKeH3AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDVKMaoe/v431f5XkUZk32gd/1bvku/TRL+NCJr4uioy9XcuAINA9xBHaPi60mS49ODwzrGnfxA67h/PDhAREwJ shcrt_281VT63521pxlmlwyzPtVwf6lBy"
}

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_281VT63521pxlmlwyzPtVwf6lBy",
      "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy",
      "created_at": "2022-04-19T16:01:23Z",
      "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_281VT1ifntUvZ72li9WAGmucxOF",
      "principals": [
        "inconshreveable.com",
        "10.2.42.9"
      ],
      "valid_after": "2022-04-19T16:01:23Z",
      "valid_until": "2022-07-18T16:01:22Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl1WUDNZfsY689785xZZajV5YyaHsDD/yQk4H9laIaJ4AAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMjgxVlQ2MzUyMXB4bG1sd3l6UHRWd2Y2bEJ5AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABiXtzTAAAAAGLVg9IAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIOdNfhjh41qFmuV8DICvY1bn6HywrT3UzfWf8VtGKeH3AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDVKMaoe/v431f5XkUZk32gd/1bvku/TRL+NCJr4uioy9XcuAINA9xBHaPi60mS49ODwzrGnfxA67h/PDhAREwJ shcrt_281VT63521pxlmlwyzPtVwf6lBy"
    }
  ],
  "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_281VT63521pxlmlwyzPtVwf6lBy

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_281VT63521pxlmlwyzPtVwf6lBy",
  "uri": "https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy",
  "created_at": "2022-04-19T16:01:23Z",
  "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_281VT1ifntUvZ72li9WAGmucxOF",
  "principals": [
    "inconshreveable.com",
    "10.2.42.9"
  ],
  "valid_after": "2022-04-19T16:01:23Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgl1WUDNZfsY689785xZZajV5YyaHsDD/yQk4H9laIaJ4AAAAIbmlzdHAyNTYAAABBBI3oSgxrOEJ+tIJ/n6VYtxQIFvynqlOHpfOAJ4x4OfmMYDkbf8dr6RAuUSf+ZC2HMCujta7EjZ9t+6v08Ue+CgkAAAAAAAAAAAAAAAIAAAAhc2hjcnRfMjgxVlQ2MzUyMXB4bG1sd3l6UHRWd2Y2bEJ5AAAAJAAAABNpbmNvbnNocmV2ZWFibGUuY29tAAAACTEwLjIuNDIuOQAAAABiXtzTAAAAAGLVg9IAAAAAAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIOdNfhjh41qFmuV8DICvY1bn6HywrT3UzfWf8VtGKeH3AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDVKMaoe/v431f5XkUZk32gd/1bvku/TRL+NCJr4uioy9XcuAINA9xBHaPi60mS49ODwzrGnfxA67h/PDhAREwJ shcrt_281VT63521pxlmlwyzPtVwf6lBy"
}

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_281VT0nNoIS8kgpKtMcFecxsGyV","public_key":"ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0= alan@work-laptop","principals":["ec2-user","root"],"valid_until":"2022-07-18T11:01:22-05:00","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 authorizing 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_281VSxdtpd29qk4pFVD16tqByYy",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT0nNoIS8kgpKtMcFecxsGyV",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2022-04-19T16:01:22Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgm/si2V22l23jzWAIILlK5K6AHxfM5vHLGMpHJe55WDoAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMjgxVlN4ZHRwZDI5cWs0cEZWRDE2dHFCeVl5AAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGJe3NIAAAAAYtWD0gAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIFSlveWzS4UEaDjASBe3rLs0zhUp5eRHE65X+JdKctf1AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDsjPYb2jwT6Vjs1Jd+u+eZAliCBF5ePII+SV/+JMihn/27oF8uJIF4gz6Mg65iMsRVt6jBoOnLUWkznC4wCjoN sucrt_281VSxdtpd29qk4pFVD16tqByYy"
}

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 authorizing 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_281VSxdtpd29qk4pFVD16tqByYy

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_281VSxdtpd29qk4pFVD16tqByYy

Response

Returns a 200 response on success

Example Response

{
  "id": "sucrt_281VSxdtpd29qk4pFVD16tqByYy",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT0nNoIS8kgpKtMcFecxsGyV",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2022-04-19T16:01:22Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgm/si2V22l23jzWAIILlK5K6AHxfM5vHLGMpHJe55WDoAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMjgxVlN4ZHRwZDI5cWs0cEZWRDE2dHFCeVl5AAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGJe3NIAAAAAYtWD0gAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIFSlveWzS4UEaDjASBe3rLs0zhUp5eRHE65X+JdKctf1AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDsjPYb2jwT6Vjs1Jd+u+eZAliCBF5ePII+SV/+JMihn/27oF8uJIF4gz6Mg65iMsRVt6jBoOnLUWkznC4wCjoN sucrt_281VSxdtpd29qk4pFVD16tqByYy"
}

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 authorizing 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_281VSxdtpd29qk4pFVD16tqByYy",
      "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy",
      "created_at": "2022-04-19T16:01:22Z",
      "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_281VT0nNoIS8kgpKtMcFecxsGyV",
      "principals": [
        "ec2-user",
        "root"
      ],
      "critical_options": {},
      "extensions": {
        "permit-pty": "",
        "permit-user-rc": ""
      },
      "valid_after": "2022-04-19T16:01:22Z",
      "valid_until": "2022-07-18T16:01:22Z",
      "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgm/si2V22l23jzWAIILlK5K6AHxfM5vHLGMpHJe55WDoAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMjgxVlN4ZHRwZDI5cWs0cEZWRDE2dHFCeVl5AAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGJe3NIAAAAAYtWD0gAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIFSlveWzS4UEaDjASBe3rLs0zhUp5eRHE65X+JdKctf1AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDsjPYb2jwT6Vjs1Jd+u+eZAliCBF5ePII+SV/+JMihn/27oF8uJIF4gz6Mg65iMsRVt6jBoOnLUWkznC4wCjoN sucrt_281VSxdtpd29qk4pFVD16tqByYy"
    }
  ],
  "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 authorizing 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_281VSxdtpd29qk4pFVD16tqByYy

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_281VSxdtpd29qk4pFVD16tqByYy",
  "uri": "https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT0nNoIS8kgpKtMcFecxsGyV",
  "principals": [
    "ec2-user",
    "root"
  ],
  "critical_options": {},
  "extensions": {
    "permit-pty": "",
    "permit-user-rc": ""
  },
  "valid_after": "2022-04-19T16:01:22Z",
  "valid_until": "2022-07-18T16:01:22Z",
  "certificate": "ecdsa-sha2-nistp256-cert-v01@openssh.com AAAAKGVjZHNhLXNoYTItbmlzdHAyNTYtY2VydC12MDFAb3BlbnNzaC5jb20AAAAgm/si2V22l23jzWAIILlK5K6AHxfM5vHLGMpHJe55WDoAAAAIbmlzdHAyNTYAAABBBK58lFzmWlDimDtBz78wVT4oauA8PjY0CiXTCEIsBNC6UwOJvZ0jdSaYNhDaa7dRV84DfBb/gKzqlXC7cVMZjl0AAAAAAAAAAAAAAAEAAAAhc3VjcnRfMjgxVlN4ZHRwZDI5cWs0cEZWRDE2dHFCeVl5AAAAFAAAAAhlYzItdXNlcgAAAARyb290AAAAAGJe3NIAAAAAYtWD0gAAAAAAAAAoAAAACnBlcm1pdC1wdHkAAAAAAAAADnBlcm1pdC11c2VyLXJjAAAAAAAAAAAAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIFSlveWzS4UEaDjASBe3rLs0zhUp5eRHE65X+JdKctf1AAAAUwAAAAtzc2gtZWQyNTUxOQAAAEDsjPYb2jwT6Vjs1Jd+u+eZAliCBF5ePII+SV/+JMihn/27oF8uJIF4gz6Mg65iMsRVt6jBoOnLUWkznC4wCjoN sucrt_281VSxdtpd29qk4pFVD16tqByYy"
}

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 authorizing 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

Replace TCP Edge Backend Module

Request

PUT/edges/tcp/{id}/backend

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"backend_id":"bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI"}' \
https://api.ngrok.com/edges/tcp/edgtcp_281VTWqDIklIrOkBDbeWLHcsVZL/backend

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Get TCP Edge Backend Module

Request

GET/edges/tcp/{id}/backend

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTWqDIklIrOkBDbeWLHcsVZL/backend

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete TCP Edge Backend Module

Request

DELETE/edges/tcp/{id}/backend

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTWqDIklIrOkBDbeWLHcsVZL/backend

Response

Returns a 204 response with no body on success

Replace TCP Edge IP Restriction Module

Request

PUT/edges/tcp/{id}/ip_restriction

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"ip_policy_ids":["ipp_281VTZRULh3eS6M8mIZmFibnNcQ"]}' \
https://api.ngrok.com/edges/tcp/edgtcp_281VTZ25JljzPzEngCY0or09A5y/ip_restriction

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_281VTZRULh3eS6M8mIZmFibnNcQ",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTZRULh3eS6M8mIZmFibnNcQ"
    }
  ]
}

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 TCP Edge IP Restriction Module

Request

GET/edges/tcp/{id}/ip_restriction

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTZ25JljzPzEngCY0or09A5y/ip_restriction

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_281VTZRULh3eS6M8mIZmFibnNcQ",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTZRULh3eS6M8mIZmFibnNcQ"
    }
  ]
}

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 TCP Edge IP Restriction Module

Request

DELETE/edges/tcp/{id}/ip_restriction

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTZ25JljzPzEngCY0or09A5y/ip_restriction

Response

Returns a 204 response with no body on success

Create TCP Edge

Create a TCP Edge

Request

POST/edges/tcp

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme tcp edge","metadata":"{\"environment\": \"staging\"}"}' \
https://api.ngrok.com/edges/tcp

Parameters

`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "description": "acme tcp edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "hostports": null,
  "backend": null,
  "ip_restriction": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

Get TCP Edge

Get a TCP Edge by ID

Request

GET/edges/tcp/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "description": "acme tcp edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "hostports": null,
  "backend": null,
  "ip_restriction": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

List TCP Edges

Returns a list of all TCP Edges on this account

Request

GET/edges/tcp

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp

Response

Returns a 200 response on success

Example Response

{
  "tcp_edges": [
    {
      "id": "edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
      "description": "acme tcp edge",
      "metadata": "{\"environment\": \"staging\"}",
      "created_at": "2022-04-19T16:01:25Z",
      "uri": "https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
      "hostports": null,
      "backend": null,
      "ip_restriction": null
    }
  ],
  "uri": "https://api.ngrok.com/edges/tcp",
  "next_page_uri": null
}

Fields

`tcp_edges`	TCPEdge	the list of all TCP Edges on this account
`uri`	string	URI of the TCP Edge list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

TCPEdge fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

Update TCP Edge

Updates a TCP Edge by ID. 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/edges/tcp/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU

Parameters

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "description": "acme tcp edge",
  "metadata": "{\"environment\": \"production\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU",
  "hostports": null,
  "backend": null,
  "ip_restriction": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

Delete TCP Edge

Delete a TCP Edge by ID

Request

DELETE/edges/tcp/{id}

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU

Response

Returns a 204 response with no body on success

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_281VT49ot9HXj3b8ajFWPY46myt",
  "uri": "https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VT49ot9HXj3b8ajFWPY46myt

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_281VT49ot9HXj3b8ajFWPY46myt

Response

Returns a 200 response on success

Example Response

{
  "id": "cert_281VT49ot9HXj3b8ajFWPY46myt",
  "uri": "https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt",
  "created_at": "2022-04-19T16:01:22Z",
  "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_281VS9tZw5Z1WxZTXn2SOUJUtVk",
      "uri": "https://api.ngrok.com/tls_certificates/cert_281VS9tZw5Z1WxZTXn2SOUJUtVk",
      "created_at": "2022-04-19T16:01:15Z",
      "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_281VT49ot9HXj3b8ajFWPY46myt",
      "uri": "https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt",
      "created_at": "2022-04-19T16:01:22Z",
      "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_281VT49ot9HXj3b8ajFWPY46myt

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_281VT49ot9HXj3b8ajFWPY46myt",
  "uri": "https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt",
  "created_at": "2022-04-19T16:01:22Z",
  "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 Edge Backend Module

Request

PUT/edges/tls/{id}/backend

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"backend_id":"bkdtg_281VTUsSudF9xQ6agLxEcrTAloW"}' \
https://api.ngrok.com/edges/tls/edgtls_281VTSY3F30XtyRpXdHg0tnZrbw/backend

Parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VTUsSudF9xQ6agLxEcrTAloW",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTUsSudF9xQ6agLxEcrTAloW"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Get TLS Edge Backend Module

Request

GET/edges/tls/{id}/backend

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTSY3F30XtyRpXdHg0tnZrbw/backend

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "backend": {
    "id": "bkdtg_281VTUsSudF9xQ6agLxEcrTAloW",
    "uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTUsSudF9xQ6agLxEcrTAloW"
  }
}

Fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

Delete TLS Edge Backend Module

Request

DELETE/edges/tls/{id}/backend

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTSY3F30XtyRpXdHg0tnZrbw/backend

Response

Returns a 204 response with no body on success

Replace TLS Edge IP Restriction Module

Request

PUT/edges/tls/{id}/ip_restriction

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"ip_policy_ids":["ipp_281VTUIT6UiJTVIFGfSe9ZPD367","ipp_281VTZ8p6wiu82A9Ixgl6LSpMtA"]}' \
https://api.ngrok.com/edges/tls/edgtls_281VTXYflLc0Rw2GGMK9uQhJeQD/ip_restriction

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_281VTUIT6UiJTVIFGfSe9ZPD367",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTUIT6UiJTVIFGfSe9ZPD367"
    },
    {
      "id": "ipp_281VTZ8p6wiu82A9Ixgl6LSpMtA",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTZ8p6wiu82A9Ixgl6LSpMtA"
    }
  ]
}

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 TLS Edge IP Restriction Module

Request

GET/edges/tls/{id}/ip_restriction

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTXYflLc0Rw2GGMK9uQhJeQD/ip_restriction

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "ip_policies": [
    {
      "id": "ipp_281VTUIT6UiJTVIFGfSe9ZPD367",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTUIT6UiJTVIFGfSe9ZPD367"
    },
    {
      "id": "ipp_281VTZ8p6wiu82A9Ixgl6LSpMtA",
      "uri": "https://api.ngrok.com/ip_policies/ipp_281VTZ8p6wiu82A9Ixgl6LSpMtA"
    }
  ]
}

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 TLS Edge IP Restriction Module

Request

DELETE/edges/tls/{id}/ip_restriction

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTXYflLc0Rw2GGMK9uQhJeQD/ip_restriction

Response

Returns a 204 response with no body on success

Replace TLS Edge Mutual TLS Module

Request

PUT/edges/tls/{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_281VTVO6IpaliXaNFTxUrN5iTtG"]}' \
https://api.ngrok.com/edges/tls/edgtls_281VTVJ64rDa1jd0nCa7pM2En1V/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 presented by the initiator of the TLS connection

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_281VTVO6IpaliXaNFTxUrN5iTtG",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VTVO6IpaliXaNFTxUrN5iTtG"
    }
  ]
}

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 TLS Edge Mutual TLS Module

Request

GET/edges/tls/{id}/mutual_tls

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTVJ64rDa1jd0nCa7pM2En1V/mutual_tls

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "certificate_authorities": [
    {
      "id": "ca_281VTVO6IpaliXaNFTxUrN5iTtG",
      "uri": "https://api.ngrok.com/certificate_authorities/ca_281VTVO6IpaliXaNFTxUrN5iTtG"
    }
  ]
}

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 TLS Edge Mutual TLS Module

Request

DELETE/edges/tls/{id}/mutual_tls

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTVJ64rDa1jd0nCa7pM2En1V/mutual_tls

Response

Returns a 204 response with no body on success

Replace TLS Edge TLS Termination Module

Request

PUT/edges/tls/{id}/tls_termination

Example Request

curl \
-XPUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"terminate_at":"edge","min_version":"1.3"}' \
https://api.ngrok.com/edges/tls/edgtls_281VTYw4JzhVAHsGLtZB1uUVWTt/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.3"
}

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 Edge TLS Termination Module

Request

GET/edges/tls/{id}/tls_termination

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTYw4JzhVAHsGLtZB1uUVWTt/tls_termination

Response

Returns a 200 response on success

Example Response

{
  "enabled": true,
  "terminate_at": "edge",
  "min_version": "1.3"
}

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 Edge TLS Termination Module

Request

DELETE/edges/tls/{id}/tls_termination

Example Request

curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTYw4JzhVAHsGLtZB1uUVWTt/tls_termination

Response

Returns a 204 response with no body on success

Create TLS Edge

Create a TLS Edge

Request

POST/edges/tls

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme tls edge","metadata":"{\"environment\": \"staging\"}","hostports":["example.com:443"]}' \
https://api.ngrok.com/edges/tls

Parameters

`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate
`mutual_tls`	EndpointMutualTLSMutate
`tls_termination`	EndpointTLSTermination

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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 presented by the initiator 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`.

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "description": "acme tls edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "hostports": [
    "example.com:443"
  ],
  "backend": null,
  "ip_restriction": null,
  "mutual_tls": null,
  "tls_termination": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

EndpointMutualTLS fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Get TLS Edge

Get a TLS Edge by ID

Request

GET/edges/tls/{id}

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "description": "acme tls edge",
  "metadata": "{\"environment\": \"staging\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "hostports": [
    "example.com:443"
  ],
  "backend": null,
  "ip_restriction": null,
  "mutual_tls": null,
  "tls_termination": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

EndpointMutualTLS fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

List TLS Edges

Returns a list of all TLS Edges on this account

Request

GET/edges/tls

Example Request

curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls

Response

Returns a 200 response on success

Example Response

{
  "tls_edges": [
    {
      "id": "edgtls_281VTPv43M39FozGo6YcX1MtWal",
      "description": "acme tls edge",
      "metadata": "{\"environment\": \"staging\"}",
      "created_at": "2022-04-19T16:01:25Z",
      "uri": "https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal",
      "hostports": [
        "example.com:443"
      ],
      "backend": null,
      "ip_restriction": null,
      "mutual_tls": null,
      "tls_termination": null
    },
    {
      "id": "edgtls_281VSaU0qZP8KEDTswG6mCYq35W",
      "description": "acme tls edge",
      "metadata": "",
      "created_at": "2022-04-19T16:01:19Z",
      "uri": "https://api.ngrok.com/edges/tls/edgtls_281VSaU0qZP8KEDTswG6mCYq35W",
      "hostports": [
        "endpoint-example.com:443"
      ],
      "backend": {
        "enabled": true,
        "backend": {
          "id": "bkdhr_281VSdmzh7sDOqD0SKztgPXP141",
          "uri": "https://api.ngrok.com/backends/http_response/bkdhr_281VSdmzh7sDOqD0SKztgPXP141"
        }
      },
      "ip_restriction": null,
      "mutual_tls": null,
      "tls_termination": null
    }
  ],
  "uri": "https://api.ngrok.com/edges/tls",
  "next_page_uri": null
}

Fields

`tls_edges`	TLSEdge	the list of all TLS Edges on this account
`uri`	string	URI of the TLS Edge list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

TLSEdge fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`ip_policies`	Ref

EndpointMutualTLS fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`certificate_authorities`	Ref	PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

EndpointTLSTermination fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`terminate_at`	string	`edge` if the ngrok edge should terminate TLS traffic, `upstream` if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if `upstream` is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
`min_version`	string	The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if `terminate_at` is set to `upstream`.

Update TLS Edge

Updates a TLS Edge by ID. 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/edges/tls/{id}

Example Request

curl \
-XPATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"metadata":"{\"environment\": \"production\"}"}' \
https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal

Parameters

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackendMutate	edge modules
`ip_restriction`	EndpointIPPolicyMutate
`mutual_tls`	EndpointMutualTLSMutate
`tls_termination`	EndpointTLSTermination

EndpointBackendMutate parameters

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend_id`	string	backend to be used to back this endpoint

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 presented by the initiator 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`.

Response

Returns a 200 response on success

Example Response

{
  "id": "edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "description": "acme tls edge",
  "metadata": "{\"environment\": \"production\"}",
  "created_at": "2022-04-19T16:01:25Z",
  "uri": "https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal",
  "hostports": [
    "example.com:443"
  ],
  "backend": null,
  "ip_restriction": null,
  "mutual_tls": null,
  "tls_termination": null
}

Fields

`id`	string	unique identifier of this edge
`description`	string	human-readable description of what this edge will be used for; optional, max 255 bytes.
`metadata`	string	arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
`created_at`	string	timestamp when the edge configuration was created, RFC 3339 format
`uri`	string	URI of the edge API resource
`hostports`	List<string>	hostports served by this edge
`backend`	EndpointBackend	edge modules
`ip_restriction`	EndpointIPPolicy
`mutual_tls`	EndpointMutualTLS
`tls_termination`	EndpointTLSTermination

EndpointBackend fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified
`backend`	Ref	backend to be used to back this endpoint

Ref fields

`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

EndpointIPPolicy fields

`enabled`	boolean	`true` if the module will be applied to traffic, `false` to disab

❮ Back to Main Docs

API Overview

API Clients

API Resources

Abuse

Agent

Backends

Certificates

Credentials

Endpoints

Events

HTTPS Edges

IP Restrictions

TCP Edges

TLS Edges

The ngrok HTTP API

Introduction

Authentication

Access the root API resource

Content Types

Versioning and API Stability

Pagination

API Clients

ngrok API Client Libraries

Terraform Provider

example.tf

API Resources

Create API Key

Request

Example Request

Parameters

Response

Example Response

Fields

Delete API Key

Request

Example Request

Response

Get API Key

Request

Example Request

Response

Example Response

Fields

List API Keys

Request

Example Request

Response

Example Response

Fields

APIKey fields

Update API Key

Request

Example Request

Parameters

Response

Example Response

Fields

Create Abuse Report

Request

Example Request

Parameters

Response

Example Response

Fields

AbuseReportHostname fields

Get Abuse Report

Request

Example Request

Response

Example Response

Fields

AbuseReportHostname fields

Create Agent Ingress

Request

Example Request

Parameters

Response

Example Response

Fields