The ngrok HTTP API is available at https://api.ngrok.com
. It
provides programmatic access to all of ngrok's resources.
The API is REST-ish. It follows most of the conventions of a REST API but breaks some when the REST model does not fit well. The API listens only on port 443 to help avoid any accidental unencrypted requests.
If you are looking to programmatically start and stop tunnels, instead consult the documentation of the ngrok agent API.
Base URL | https://api.ngrok.com |
---|---|
Authentication | Bearer token authentication with an ngrok.com API key token |
API keys to access the ngrok.com HTTP API can be provisioned on the
API Keys page of your ngrok dashboard. API keys can also be created via the
API keys API Resource. All requests to the
API must include an API key as a bearer token in the Authorization header
as well as an ngrok-version
header as demonstrated in the following example.
curl -H "authorization: Bearer {API_KEY}" -H "ngrok-version: 2" https://api.ngrok.com/
All request bodies sent to the API must use a content type of
application/json
. Ensure that your client sets the request's
Content-Type
header appropriately. All responses returned by
the API will also be returned with an
application/json
content type.
The caller must specify a version by sending an
ngrok-version
header with each request. The latest version is
2
. Versions 0
and 1
are deprecated.
The ngrok API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version. The following non-breaking changes to the API may be made to existing versions without an opt-in:
List endpoints can be paginated using the query parameters
limit
and before_id
. Results are returned
ordered from newest to oldest. The maximum value of limit
is
100. If a limit is not specified, it will default to 100. If
before_id
is not specified, the first page of results will be
returned. You can provide an explicit value for before_id
to
retrieve items created before the given ID. Each response to a list
request will include a next_page_uri
field, which will be the
full URL you can request to retrieve the next page of results. If there
are no more results, next_page_uri
will be null
.
ngrok's API is designed to be simple enough to be called with
curl
and the HTTP library in your programming language of
choice. We also believe that higher-level interfaces are better fits
depending on the type of automation you're building. We publish a number
of official API clients and tools that make automating your ngrok
workflows easy.
We've also built API access into the latest ngrok agent v3 using the
ngrok api
command. For more information, check out the
ngrok agent reference.
ngrok publishes API client libraries to make working with ngrok resources feel native and fluent in your favorite programming language. All of our client libraries are open source and published under the ngrok github organization.
Language | Installation | Documentation | 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 |
When you use ngrok resources as part of production infrastructure, it is an industry best practice to define them using an infrastructure-as-code (IaC) tool like Terraform. We publish an official Terraform provider that consumes the ngrok API to manage ngrok resources in this way.
Consult the documentation for the ngrok Terraform provider on Hashicorp's Terraform Registry.
# Configure the ngrok provider
provider "ngrok" {
api_key = "{API_KEY}"
}
# Provision an ngrok domain
resource "ngrok_reserved_domain" "my_domain" {
name = "my-domain.example.com"
region = "us"
certificate_management_policy {
authority = "letsencrypt"
private_key_type = "ecdsa"
}
}
Create a new API key. The generated API key can be used to authenticate to the ngrok API.
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
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 |
Returns a 200 response on success
{
"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"
}
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 an API key by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI
Returns a 204 response with no body on success
Get the details of an API key by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys/ak_281VSAsp9vBP4HDI1LbjLRuzYOI
Returns a 200 response on success
{
"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
}
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 all API keys owned by this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/api_keys
Returns a 200 response on success
{
"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
}
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 |
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 attributes of an API key by ID.
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
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 |
Returns a 200 response on success
{
"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
}
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. |
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
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
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. |
Returns a 200 response on success
{
"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"
}
]
}
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
|
hostnames |
AbuseReportHostname | an array of hostname statuses related to the report |
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
|
Get the detailed status of abuse report by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/abuse_reports/abrp_281VSpi6sapq6HFrXV9oYDcn381
Returns a 200 response on success
{
"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"
}
]
}
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
|
hostnames |
AbuseReportHostname | an array of hostname statuses related to the report |
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
|
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.
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
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. |
Returns a 200 response on success
{
"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"
}
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 an Agent Ingress by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0
Returns a 204 response with no body on success
Get the details of an Agent Ingress by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses/agin_281VT7iCDU8U21OBKxXviKHw0q0
Returns a 200 response on success
{
"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"
}
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 all Agent Ingresses owned by this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses
Returns a 200 response on success
{
"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
}
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 |
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 attributes of an Agent Ingress by ID.
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
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 |
Returns a 200 response on success
{
"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"
}
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 |
Upload a new Certificate Authority
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
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 |
Returns a 200 response on success
{
"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 |
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 a Certificate Authority
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D
Returns a 204 response with no body on success
Get detailed information about a certficate authority
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/certificate_authorities/ca_281VT17gcUXCLifWhnP2vjjgK8D
Returns a 200 response on success
{
"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": []
}
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 all Certificate Authority on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/certificate_authorities
Returns a 200 response on success
{
"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
}
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 |
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 attributes of a Certificate Authority by ID
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
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. |
Returns a 200 response on success
{
"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": []
}
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 all active endpoints on the account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints
Returns a 200 response on success
{
"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
}
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 |
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 |
hostport |
string | hostport served by this endpoint (hostname:port) |
type |
string |
whether the endpoint is |
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Get the status of an endpoint by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/endpoints/ep_281VSnLqRt28JBuzynQIuwoCwj0
Returns a 200 response on success
{
"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 |
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 |
hostport |
string | hostport served by this endpoint (hostname:port) |
type |
string |
whether the endpoint is |
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Create a new Event Destination. It will not apply to anything until it is associated with an Event Subscription.
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
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
|
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: |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
Returns a 200 response on success
{
"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"
}
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
|
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: |
uri |
string | URI of the Event Destination API resource. |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
Delete an Event Destination. If the Event Destination is still referenced by an Event Subscription.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_destinations/ed_281VSy3PDTkkZil3Oz6X2ycCjZu
Returns a 204 response with no body on success
Get detailed information about an Event Destination by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_destinations/ed_281VSy3PDTkkZil3Oz6X2ycCjZu
Returns a 200 response on success
{
"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"
}
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
|
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: |
uri |
string | URI of the Event Destination API resource. |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
List all Event Destinations on this account.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_destinations
Returns a 200 response on success
{
"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
}
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. |
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
|
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: |
uri |
string | URI of the Event Destination API resource. |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
Update attributes of an Event Destination.
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
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
|
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: |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
Returns a 200 response on success
{
"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"
}
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
|
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: |
uri |
string | URI of the Event Destination API resource. |
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
delivery_stream_arn |
string |
An Amazon Resource Name specifying the Firehose delivery stream to deposit events into. |
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. |
role_arn |
string |
An ARN that specifies the role that ngrok should use to deliver to the configured target. |
---|
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. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
stream_arn |
string |
An Amazon Resource Name specifying the Kinesis stream to deposit events into. |
auth |
AWSAuth |
Configuration for how to authenticate into your AWS account. Exactly
one of |
---|---|---|
log_group_arn |
string |
An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into. |
Add an additional type for which this event subscription will trigger
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
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 |
Returns a 200 response on success
{
"type": "ip_policy_updated.v0",
"uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
Remove a type for which this event subscription will trigger
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0
Returns a 204 response with no body on success
Get the details for a given type that triggers for the given event subscription
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0
Returns a 200 response on success
{
"type": "ip_policy_updated.v0",
"uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
List the types for which this event subscription will trigger
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources
Returns a 200 response on success
{
"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"
}
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. |
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
Update the type for which this event subscription will trigger
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
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 |
Returns a 200 response on success
{
"type": "ip_policy_updated.v0",
"uri": "https://api.ngrok.com/event_subscriptions/esb_281VSyijeipwrHZ5SS9tNQT8Hq3/sources/ip_policy_updated.v0"
}
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
Create an Event Subscription.
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
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. |
type |
string |
Type of event for which an event subscription will trigger |
---|
Returns a 200 response on success
{
"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"
}
]
}
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 |
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Delete an Event Subscription.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX
Returns a 204 response with no body on success
Get an Event Subscription by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions/esb_281VSzYRZ1FetGZzTIb387nk0KX
Returns a 200 response on success
{
"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"
}
]
}
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 |
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
List this Account’s Event Subscriptions.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/event_subscriptions
Returns a 200 response on success
{
"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
}
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. |
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 |
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Update an Event Subscription.
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
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. |
type |
string |
Type of event for which an event subscription will trigger |
---|
Returns a 200 response on success
{
"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"
}
]
}
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 |
type |
string |
Type of event for which an event subscription will trigger |
---|---|---|
uri |
string | URI of the Event Source API resource. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Create a new Failover backend
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
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 |
Returns a 200 response on success
{
"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"
]
}
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 a Failover backend by ID.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq
Returns a 204 response with no body on success
Get detailed information about a Failover backend by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover/bkdfo_281VTBNXZyW72ucnIvLmYbzXRPq
Returns a 200 response on success
{
"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"
]
}
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 all Failover backends on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/failover
Returns a 200 response on success
{
"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
}
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 |
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 by ID
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
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 |
Returns a 200 response on success
{
"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": []
}
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 |
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
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 |
Returns a 200 response on success
{
"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 |
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 |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD
Returns a 204 response with no body on success
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response/bkdhr_281VT7cQ7vQwQ6CkKsF2YlnFCwD
Returns a 200 response on success
{
"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 |
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 |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/backends/http_response
Returns a 200 response on success
{
"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
}
backends |
HTTPResponseBackend | |
---|---|---|
uri |
string | |
next_page_uri |
string |
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 |
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
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 |
Returns a 200 response on success
{
"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
}
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 |
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"certificate_authorities": [
{
"id": "ca_281VTOvsYutJN79tshryTFd8YcT",
"uri": "https://api.ngrok.com/certificate_authorities/ca_281VTOvsYutJN79tshryTFd8YcT"
}
]
}
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTOIZuRn6l6t3RbPs90EA84V/mutual_tls
Returns a 200 response on success
{
"enabled": true,
"certificate_authorities": [
{
"id": "ca_281VTOvsYutJN79tshryTFd8YcT",
"uri": "https://api.ngrok.com/certificate_authorities/ca_281VTOvsYutJN79tshryTFd8YcT"
}
]
}
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTOIZuRn6l6t3RbPs90EA84V/mutual_tls
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTBTkVvIKR5LBqGWQHYq102f/routes/edghtsrt_281VTAkONRZIfHtyT0jU4xjMghW/backend
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VT5n7vwSluBr7DQYj1s3CBDL"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTBTkVvIKR5LBqGWQHYq102f/routes/edghtsrt_281VTAkONRZIfHtyT0jU4xjMghW/backend
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"tripped_duration": 120,
"rolling_window": 300,
"num_buckets": 5,
"volume_threshold": 20,
"error_threshold_percentage": 0.2
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTAlbmmCtnz8aIQ4rZ9Watd0/routes/edghtsrt_281VTF1H2vBrsGv4xB7mQHSjCe6/circuit_breaker
Returns a 200 response on success
{
"enabled": true,
"tripped_duration": 120,
"rolling_window": 300,
"num_buckets": 5,
"volume_threshold": 20,
"error_threshold_percentage": 0.2
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTAlbmmCtnz8aIQ4rZ9Watd0/routes/edghtsrt_281VTF1H2vBrsGv4xB7mQHSjCe6/circuit_breaker
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|
Returns a 200 response on success
{
"enabled": true
}
enabled |
boolean |
|
---|
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTICZn3JxyemtDzdDponcV1i/routes/edghtsrt_281VTFoeCkjSj68dhokLNbeea4O/compression
Returns a 200 response on success
{
"enabled": true
}
enabled |
boolean |
|
---|
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTICZn3JxyemtDzdDponcV1i/routes/edghtsrt_281VTFoeCkjSj68dhokLNbeea4O/compression
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"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"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTI3xOHmd0aG61mAvGP62Z6o/routes/edghtsrt_281VTHX9DkHujAr6IyXV6o2fYum/ip_restriction
Returns a 200 response on success
{
"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"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTI3xOHmd0aG61mAvGP62Z6o/routes/edghtsrt_281VTHX9DkHujAr6IyXV6o2fYum/ip_restriction
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
Returns a 200 response on success
{
"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
}
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTEQGEkE0JRZMAQyfOhLX9U2/routes/edghtsrt_281VTDhQz1Pn2Q6vtJMpo3jNhbm/oauth
Returns a 200 response on success
{
"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
}
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTEQGEkE0JRZMAQyfOhLX9U2/routes/edghtsrt_281VTDhQz1Pn2Q6vtJMpo3jNhbm/oauth
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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. |
Returns a 200 response on success
{
"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"
]
}
enabled |
boolean |
|
---|---|---|
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. |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTJwvbSCgr00EB0BsF3AZxDh/routes/edghtsrt_281VTGcUEoT0QK6I4tWaIQV7duR/oidc
Returns a 200 response on success
{
"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"
]
}
enabled |
boolean |
|
---|---|---|
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. |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTJwvbSCgr00EB0BsF3AZxDh/routes/edghtsrt_281VTGcUEoT0QK6I4tWaIQV7duR/oidc
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"add": {
"x-frontend": "ngrok"
},
"remove": [
"cache-control"
]
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTFOBEJOuQ5dXQc8v8uRkwh9/routes/edghtsrt_281VTESQEq3fmk37WsXyk4wcpC1/request_headers
Returns a 200 response on success
{
"enabled": true,
"add": {
"x-frontend": "ngrok"
},
"remove": [
"cache-control"
]
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTFOBEJOuQ5dXQc8v8uRkwh9/routes/edghtsrt_281VTESQEq3fmk37WsXyk4wcpC1/request_headers
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"add": {
"content-security-policy": "script-src 'self'",
"x-frame-options": "DENY"
},
"remove": []
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTDMn17IPi6TcwF9U2h06VJG/routes/edghtsrt_281VTDDL1TZPcbooRrnkrSgAwBw/response_headers
Returns a 200 response on success
{
"enabled": true,
"add": {
"content-security-policy": "script-src 'self'",
"x-frame-options": "DENY"
},
"remove": []
}
enabled |
boolean |
|
---|---|---|
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 |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTDMn17IPi6TcwF9U2h06VJG/routes/edghtsrt_281VTDDL1TZPcbooRrnkrSgAwBw/response_headers
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
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
|
Returns a 200 response on success
{
"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"
}
enabled |
boolean |
|
---|---|---|
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 |
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
|
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNsKKnioB1QNHXsRoeWCPPc/routes/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/saml
Returns a 200 response on success
{
"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"
}
enabled |
boolean |
|
---|---|---|
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 |
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
|
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNsKKnioB1QNHXsRoeWCPPc/routes/edghtsrt_281VTO2avbSpnxbNBxcI9y4cbBE/saml
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
Returns a 200 response on success
{
"enabled": true,
"provider": "TWILIO",
"secret": "secret_token"
}
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTO7BArEgS26LC5E0slWMt3g/routes/edghtsrt_281VTQ51icCsDPz6T41bNMJXF0Q/webhook_verification
Returns a 200 response on success
{
"enabled": true,
"provider": "TWILIO",
"secret": "secret_token"
}
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTO7BArEgS26LC5E0slWMt3g/routes/edghtsrt_281VTQ51icCsDPz6T41bNMJXF0Q/webhook_verification
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|
Returns a 200 response on success
{
"enabled": true
}
enabled |
boolean |
|
---|
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTQs5x5F20R1aPPCqneRwNgT/routes/edghtsrt_281VTRd1jjHokPCxDz0x3CtQbVW/websocket_tcp_converter
Returns a 200 response on success
{
"enabled": true
}
enabled |
boolean |
|
---|
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
Returns a 204 response with no body on success
Create an HTTPS Edge Route
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
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 |
ip_restriction |
EndpointIPPolicyMutate |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAMLMutate |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Returns a 200 response on success
{
"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
}
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Get an HTTPS Edge Route by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm
Returns a 200 response on success
{
"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
}
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
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.
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
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 |
ip_restriction |
EndpointIPPolicyMutate |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAMLMutate |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Returns a 200 response on success
{
"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
}
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Delete an HTTPS Edge Route by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT6kmMfszIxuhVrmwbOPyXxq/routes/edghtsrt_281VTCNKnpg09lT3cayFBtDRFPm
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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
|
Returns a 200 response on success
{
"enabled": true,
"terminate_at": "edge",
"min_version": "1.3"
}
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNCqUW9Q6u0uH0gDA9PRExk/tls_termination
Returns a 200 response on success
{
"enabled": true,
"terminate_at": "edge",
"min_version": "1.3"
}
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VTNCqUW9Q6u0uH0gDA9PRExk/tls_termination
Returns a 204 response with no body on success
Create an HTTPS Edge
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
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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
|
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Get an HTTPS Edge by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Returns a list of all HTTPS Edges on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https
Returns a 200 response on success
{
"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
}
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 |
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 |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
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.
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
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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
|
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
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 |
ip_restriction |
EndpointIPPolicy |
ip restriction module configuration or |
circuit_breaker |
EndpointCircuitBreaker |
circuit breaker module configuration or |
compression |
EndpointCompression |
compression module configuration or |
request_headers |
EndpointRequestHeaders |
request headers module configuration or |
response_headers |
EndpointResponseHeaders |
response headers module configuration or |
webhook_verification |
EndpointWebhookValidation |
webhook verification module configuration or |
oauth |
EndpointOAuth |
oauth module configuration or |
saml |
EndpointSAML |
saml module configuration or |
oidc |
EndpointOIDC |
oidc module configuration or |
websocket_tcp_converter |
EndpointWebsocketTCPConverter |
websocket to tcp adapter configuration or |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
provider |
string |
a string indicating which webhook provider will be sending webhooks
to this endpoint. Value must be one of the supported providers:
|
secret |
string |
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
enabled |
boolean |
|
---|---|---|
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. |
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 |
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
|
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
|
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. |
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’ |
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
|
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
|
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 |
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
|
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
|
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 |
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
|
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
|
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 |
enabled |
boolean |
|
---|---|---|
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 |
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
|
enabled |
boolean |
|
---|---|---|
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. |
enabled |
boolean |
|
---|
Delete an HTTPS Edge by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_281VT89MbGew8qSxfYqb4CdXGH7
Returns a 204 response with no body on success
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.
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
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. |
Returns a 200 response on success
{
"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 |
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 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.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB
Returns a 204 response with no body on success
Get detailed information about an IP policy by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policies/ipp_281VSBiy4r0HL5yaeQwrfDBrAOB
Returns a 200 response on success
{
"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\"}"
}
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 all IP policies on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policies
Returns a 200 response on success
{
"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
}
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 |
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 attributes of an IP policy by ID
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
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. |
Returns a 200 response on success
{
"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\"}"
}
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 a new IP policy rule attached to an IP Policy.
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
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 |
Returns a 200 response on success
{
"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 |
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Delete an IP policy rule.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ
Returns a 204 response with no body on success
Get detailed information about an IP policy rule by ID.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policy_rules/ipr_281VSx5DhHmBReHTT6sUbgs0vgZ
Returns a 200 response on success
{
"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"
}
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
List all IP policy rules on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_policy_rules
Returns a 200 response on success
{
"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
}
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 |
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Update attributes of an IP policy rule by ID
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
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. |
Returns a 200 response on success
{
"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"
}
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 |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Create a new IP restriction
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
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: |
ip_policy_ids |
List<string> |
the set of IP policy identifiers that are used to enforce the restriction |
Returns a 200 response on success
{
"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 |
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: |
ip_policies |
Ref |
the set of IP policies that are used to enforce the restriction |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Delete an IP restriction
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt
Returns a 204 response with no body on success
Get detailed information about an IP restriction
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions/ipx_281VSyVE0wH5VxK8PT991OpcaUt
Returns a 200 response on success
{
"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"
}
]
}
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: |
ip_policies |
Ref |
the set of IP policies that are used to enforce the restriction |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
List all IP restrictions on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ip_restrictions
Returns a 200 response on success
{
"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
}
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 |
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: |
ip_policies |
Ref |
the set of IP policies that are used to enforce the restriction |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Update attributes of an IP restriction by ID
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
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 |
Returns a 200 response on success
{
"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"
}
]
}
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: |
ip_policies |
Ref |
the set of IP policies that are used to enforce the restriction |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
Create a new reserved address.
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
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) |
Returns a 200 response on success
{
"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
}
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 a reserved address.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX
Returns a 204 response with no body on success
Get the details of a reserved address.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_addrs/ra_27zPQF5dYWaDnNkX9H7cumNLSZX
Returns a 200 response on success
{
"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"
}
}
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 all reserved addresses on this account.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_addrs
Returns a 200 response on success
{
"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
}
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 |
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 the attributes of a reserved address.
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
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. |
Returns a 200 response on success
{
"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"
}
}
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 a new reserved domain.
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
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 |
ReservedDomainCertPolicy |
configuration for automatic management of TLS certificates for this
domain, or null if automatic management is disabled. Optional,
mutually exclusive with |
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. |
Returns a 200 response on success
{
"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 |
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. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
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. |
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 |
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 a reserved domain.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs
Returns a 204 response with no body on success
Get the details of a reserved domain.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs
Returns a 200 response on success
{
"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
}
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. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
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. |
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 |
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 all reserved domains on this account.
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains
Returns a 200 response on success
{
"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
}
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 |
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. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
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. |
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 |
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 the attributes of a reserved domain.
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
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 |
ReservedDomainCertPolicy |
configuration for automatic management of TLS certificates for this
domain, or null if automatic management is disabled. Optional,
mutually exclusive with |
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. |
Returns a 200 response on success
{
"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
}
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. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
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. |
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 |
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 the certificate management policy attached to a reserved domain.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs/certificate_management_policy
Returns a 204 response with no body on success
Detach the certificate attached to a reserved domain.
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/reserved_domains/rd_281VS7M93ynIx1xAz19JU7m9pWs/certificate
Returns a 204 response with no body on success
Create a new SSH Certificate Authority
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
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 |
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
|
Returns a 200 response on success
{
"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"
}
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 an SSH Certificate Authority
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d
Returns a 204 response with no body on success
Get detailed information about an SSH Certficate Authority
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_certificate_authorities/sshca_281VSyZ5CbmEEF3wsJLu84DK05d
Returns a 200 response on success
{
"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"
}
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 all SSH Certificate Authorities on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_certificate_authorities
Returns a 200 response on success
{
"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
}
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 |
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 an SSH Certificate Authority
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
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. |
Returns a 200 response on success
{
"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"
}
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 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.
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
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
|
public_key |
string |
the PEM-encoded public key of the SSH keypair that will be used to authenticate |
Returns a 200 response on success
{
"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"
]
}
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
|
Delete an ssh_credential by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5
Returns a 204 response with no body on success
Get detailed information about an ssh_credential
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_credentials/sshcr_281VSqzhNBtReJAzZkuS1EhqqC5
Returns a 200 response on success
{
"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"
]
}
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
|
List all ssh credentials on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_credentials
Returns a 200 response on success
{
"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
}
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 |
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
|
Update attributes of an ssh_credential by ID
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
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
|
Returns a 200 response on success
{
"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"
]
}
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
|
Create a new SSH Host Certificate
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
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
|
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. |
Returns a 200 response on success
{
"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"
}
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 |
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys format. this
value should be placed in a |
Delete an SSH Host Certificate
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy
Returns a 204 response with no body on success
Get detailed information about an SSH Host Certficate
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates/shcrt_281VT63521pxlmlwyzPtVwf6lBy
Returns a 200 response on success
{
"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"
}
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 |
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys format. this
value should be placed in a |
List all SSH Host Certificates issued on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_host_certificates
Returns a 200 response on success
{
"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
}
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 |
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 |
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys format. this
value should be placed in a |
Update an SSH Host Certificate
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
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. |
Returns a 200 response on success
{
"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"
}
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 |
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys format. this
value should be placed in a |
Create a new SSH User Certificate
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
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:
|
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:
|
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 |
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. |
Returns a 200 response on success
{
"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"
}
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 |
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:
|
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:
|
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys Format. this
value should be placed in a |
Delete an SSH User Certificate
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy
Returns a 204 response with no body on success
Get detailed information about an SSH User Certficate
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_user_certificates/sucrt_281VSxdtpd29qk4pFVD16tqByYy
Returns a 200 response on success
{
"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"
}
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 |
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:
|
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:
|
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys Format. this
value should be placed in a |
List all SSH User Certificates issued on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/ssh_user_certificates
Returns a 200 response on success
{
"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
}
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 |
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 |
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:
|
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:
|
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys Format. this
value should be placed in a |
Update an SSH User Certificate
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
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. |
Returns a 200 response on success
{
"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"
}
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 |
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:
|
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:
|
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
|
certificate |
string |
the signed SSH certificate in OpenSSH Authorized Keys Format. this
value should be placed in a |
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
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTWqDIklIrOkBDbeWLHcsVZL/backend
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTTnUIDi4WCdhjkDe9IOBxWI"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTWqDIklIrOkBDbeWLHcsVZL/backend
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"ip_policies": [
{
"id": "ipp_281VTZRULh3eS6M8mIZmFibnNcQ",
"uri": "https://api.ngrok.com/ip_policies/ipp_281VTZRULh3eS6M8mIZmFibnNcQ"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTZ25JljzPzEngCY0or09A5y/ip_restriction
Returns a 200 response on success
{
"enabled": true,
"ip_policies": [
{
"id": "ipp_281VTZRULh3eS6M8mIZmFibnNcQ",
"uri": "https://api.ngrok.com/ip_policies/ipp_281VTZRULh3eS6M8mIZmFibnNcQ"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTZ25JljzPzEngCY0or09A5y/ip_restriction
Returns a 204 response with no body on success
Create a TCP Edge
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
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 |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
Get a TCP Edge by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
Returns a list of all TCP Edges on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp
Returns a 200 response on success
{
"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
}
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 |
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
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.
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
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 |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
Delete a TCP Edge by ID
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tcp/edgtcp_281VTKYZMpVtPhVLLMJqYH1qJsU
Returns a 204 response with no body on success
Upload a new TLS certificate
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
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. |
Returns a 200 response on success
{
"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": ""
}
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 |
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 a TLS certificate
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt
Returns a 204 response with no body on success
Get detailed information about a TLS certificate
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tls_certificates/cert_281VT49ot9HXj3b8ajFWPY46myt
Returns a 200 response on success
{
"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": ""
}
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 |
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 all TLS certificates on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/tls_certificates
Returns a 200 response on success
{
"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
}
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 |
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 |
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 attributes of a TLS Certificate by ID
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
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. |
Returns a 200 response on success
{
"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": ""
}
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 |
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 |
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
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VTUsSudF9xQ6agLxEcrTAloW",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTUsSudF9xQ6agLxEcrTAloW"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTSY3F30XtyRpXdHg0tnZrbw/backend
Returns a 200 response on success
{
"enabled": true,
"backend": {
"id": "bkdtg_281VTUsSudF9xQ6agLxEcrTAloW",
"uri": "https://api.ngrok.com/backends/tunnel_group/bkdtg_281VTUsSudF9xQ6agLxEcrTAloW"
}
}
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTSY3F30XtyRpXdHg0tnZrbw/backend
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"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"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTXYflLc0Rw2GGMK9uQhJeQD/ip_restriction
Returns a 200 response on success
{
"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"
}
]
}
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTXYflLc0Rw2GGMK9uQhJeQD/ip_restriction
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
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 |
Returns a 200 response on success
{
"enabled": true,
"certificate_authorities": [
{
"id": "ca_281VTVO6IpaliXaNFTxUrN5iTtG",
"uri": "https://api.ngrok.com/certificate_authorities/ca_281VTVO6IpaliXaNFTxUrN5iTtG"
}
]
}
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTVJ64rDa1jd0nCa7pM2En1V/mutual_tls
Returns a 200 response on success
{
"enabled": true,
"certificate_authorities": [
{
"id": "ca_281VTVO6IpaliXaNFTxUrN5iTtG",
"uri": "https://api.ngrok.com/certificate_authorities/ca_281VTVO6IpaliXaNFTxUrN5iTtG"
}
]
}
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTVJ64rDa1jd0nCa7pM2En1V/mutual_tls
Returns a 204 response with no body on success
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
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
Returns a 200 response on success
{
"enabled": true,
"terminate_at": "edge",
"min_version": "1.3"
}
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTYw4JzhVAHsGLtZB1uUVWTt/tls_termination
Returns a 200 response on success
{
"enabled": true,
"terminate_at": "edge",
"min_version": "1.3"
}
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
curl \
-XDELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTYw4JzhVAHsGLtZB1uUVWTt/tls_termination
Returns a 204 response with no body on success
Create a TLS Edge
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
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 |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
Returns a 200 response on success
{
"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 |
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
Get a TLS Edge by ID
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls/edgtls_281VTPv43M39FozGo6YcX1MtWal
Returns a 200 response on success
{
"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 |
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
Returns a list of all TLS Edges on this account
curl \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/tls
Returns a 200 response on success
{
"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
}
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 |
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|---|---|
ip_policies |
Ref |
enabled |
boolean |
|
---|---|---|
certificate_authorities |
Ref |
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together. |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
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.
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
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 |
enabled |
boolean |
|
---|---|---|
backend_id |
string | backend to be used to back this endpoint |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
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 |
enabled |
boolean |
|
---|---|---|
terminate_at |
string |
|
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
|
Returns a 200 response on success
{
"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
}
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 |
enabled |
boolean |
|
---|---|---|
backend |
Ref | backend to be used to back this endpoint |
id |
string | a resource identifier |
---|---|---|
uri |
string | a uri for locating a resource |
enabled |
boolean |
|
---|