Skip to main content

Edges HTTPS Routes

Create HTTPS Edge Route

Create an HTTPS Edge Route

Request

POST /edges/https/{edge_id}/routes

Example Request

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

Parameters

NameTypeDescription
edge_idstringunique identifier of this edge
match_typestringType of match to use for this route. Valid values are "exact_path" and "path_prefix".
matchstringRoute selector: "/blog" or "example.com" or "example.com/blog"
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
backendEndpointBackendMutatebackend module configuration or null
ip_restrictionEndpointIPPolicyMutateip restriction module configuration or null
circuit_breakerEndpointCircuitBreakercircuit breaker module configuration or null
compressionEndpointCompressioncompression module configuration or null
request_headersEndpointRequestHeadersrequest headers module configuration or null
response_headersEndpointResponseHeadersresponse headers module configuration or null
webhook_verificationEndpointWebhookValidationwebhook verification module configuration or null
oauthEndpointOAuthoauth module configuration or null
samlEndpointSAMLMutatesaml module configuration or null
oidcEndpointOIDCoidc module configuration or null
websocket_tcp_converterEndpointWebsocketTCPConverterwebsocket to tcp adapter configuration or null
user_agent_filterEndpointUserAgentFilter
policyEndpointPolicythe traffic policy associated with this edge or null

EndpointBackendMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backend_idstringbackend to be used to back this endpoint

EndpointIPPolicyMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policy_idsList<string>list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointCircuitBreaker parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
tripped_durationuint32Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_windowuint32Integer number of seconds in the statistical rolling window that metrics are retained for.
num_bucketsuint32Integer number of buckets into which metrics are retained. Max 128.
volume_thresholduint32Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentagefloat64Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression parameters

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

EndpointRequestHeaders parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<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
removeList<string>a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<string, string>a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
removeList<string>a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointWebhookValidation parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerstringa string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification
secretstringa string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerEndpointOAuthProvideran object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_intervaluint32Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider parameters

NameTypeDescription
githubEndpointOAuthGitHubconfiguration for using github as the identity provider
facebookEndpointOAuthFacebookconfiguration for using facebook as the identity provider
microsoftEndpointOAuthMicrosoftconfiguration for using microsoft as the identity provider
googleEndpointOAuthGoogleconfiguration for using google as the identity provider
linkedinEndpointOAuthLinkedInconfiguration for using linkedin as the identity provider
gitlabEndpointOAuthGitLabconfiguration for using gitlab as the identity provider
twitchEndpointOAuthTwitchconfiguration for using twitch as the identity provider
amazonEndpointOAuthAmazonconfiguration for using amazon as the identity provider

EndpointOAuthGitHub parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teamsList<string>a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizationsList<string>a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthGitLab parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthTwitch parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthAmazon parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointSAMLMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadatastringThe full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authnbooleanIf 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_initiatedbooleanIf true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groupsList<string>If present, only users who are a member of one of the listed groups may access the target endpoint.
nameid_formatstringDefines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuerstringURL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_idstringThe OIDC app's client ID and OIDC audience.
client_secretstringThe OIDC app's client secret.
scopesList<string>The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter parameters

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

EndpointUserAgentFilter parameters

NameTypeDescription
enabledboolean
allowList<string>
denyList<string>

EndpointPolicy parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
inboundEndpointRulethe inbound rules of the traffic policy.
outboundEndpointRulethe outbound rules on the traffic policy.

EndpointRule parameters

NameTypeDescription
expressionsList<string>cel expressions that filter traffic the policy rule applies to.
actionsEndpointActionthe set of actions on a policy rule.
namestringthe name of the rule that is part of the traffic policy.

EndpointAction parameters

NameTypeDescription
typestringthe type of action on the policy rule.
configobjectthe configuration for the action on the policy rule.

Response

Returns a 201 response on success

Example Response

{
"backend": null,
"circuit_breaker": null,
"compression": null,
"created_at": "2024-02-16T19:35:33Z",
"description": "acme edge route",
"edge_id": "edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3",
"id": "edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"ip_restriction": null,
"match": "/",
"match_type": "path_prefix",
"metadata": "{\"environment\": \"staging\"}",
"oauth": null,
"oidc": null,
"policy": null,
"request_headers": null,
"response_headers": null,
"saml": null,
"uri": "https://api.ngrok.com/edges/https/edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3/routes/edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}

Fields

NameTypeDescription
edge_idstringunique identifier of this edge
idstringunique identifier of this edge route
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
match_typestringType of match to use for this route. Valid values are "exact_path" and "path_prefix".
matchstringRoute selector: "/blog" or "example.com" or "example.com/blog"
uristringURI of the edge API resource
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
backendEndpointBackendbackend module configuration or null
ip_restrictionEndpointIPPolicyip restriction module configuration or null
circuit_breakerEndpointCircuitBreakercircuit breaker module configuration or null
compressionEndpointCompressioncompression module configuration or null
request_headersEndpointRequestHeadersrequest headers module configuration or null
response_headersEndpointResponseHeadersresponse headers module configuration or null
webhook_verificationEndpointWebhookValidationwebhook verification module configuration or null
oauthEndpointOAuthoauth module configuration or null
samlEndpointSAMLsaml module configuration or null
oidcEndpointOIDCoidc module configuration or null
websocket_tcp_converterEndpointWebsocketTCPConverterwebsocket to tcp adapter configuration or null
user_agent_filterEndpointUserAgentFilter
policyEndpointPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointCircuitBreaker fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
tripped_durationuint32Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_windowuint32Integer number of seconds in the statistical rolling window that metrics are retained for.
num_bucketsuint32Integer number of buckets into which metrics are retained. Max 128.
volume_thresholduint32Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentagefloat64Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields

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

EndpointRequestHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<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
removeList<string>a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<string, string>a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
removeList<string>a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointWebhookValidation fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerstringa string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification
secretstringa string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerEndpointOAuthProvideran object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_intervaluint32Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider fields

NameTypeDescription
githubEndpointOAuthGitHubconfiguration for using github as the identity provider
facebookEndpointOAuthFacebookconfiguration for using facebook as the identity provider
microsoftEndpointOAuthMicrosoftconfiguration for using microsoft as the identity provider
googleEndpointOAuthGoogleconfiguration for using google as the identity provider
linkedinEndpointOAuthLinkedInconfiguration for using linkedin as the identity provider
gitlabEndpointOAuthGitLabconfiguration for using gitlab as the identity provider
twitchEndpointOAuthTwitchconfiguration for using twitch as the identity provider
amazonEndpointOAuthAmazonconfiguration for using amazon as the identity provider

EndpointOAuthGitHub fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teamsList<string>a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizationsList<string>a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthGitLab fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthTwitch fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthAmazon fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointSAML fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadatastringThe full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authnbooleanIf 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_initiatedbooleanIf true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groupsList<string>If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_idstringThe 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_urlstringThe 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_urlstringThe 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_pemstringPEM-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_urlstringA 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_formatstringDefines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuerstringURL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_idstringThe OIDC app's client ID and OIDC audience.
client_secretstringThe OIDC app's client secret.
scopesList<string>The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

EndpointUserAgentFilter fields

NameTypeDescription
enabledboolean
allowList<string>
denyList<string>

EndpointPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
inboundEndpointRulethe inbound rules of the traffic policy.
outboundEndpointRulethe outbound rules on the traffic policy.

EndpointRule fields

NameTypeDescription
expressionsList<string>cel expressions that filter traffic the policy rule applies to.
actionsEndpointActionthe set of actions on a policy rule.
namestringthe name of the rule that is part of the traffic policy.

EndpointAction fields

NameTypeDescription
typestringthe type of action on the policy rule.
configobjectthe configuration for the action on the policy rule.

Get HTTPS Edge Route

Get an HTTPS Edge Route by ID

Request

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

Example Request

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

Response

Returns a 200 response on success

Example Response

{
"backend": null,
"circuit_breaker": null,
"compression": null,
"created_at": "2024-02-16T19:35:33Z",
"description": "acme edge route",
"edge_id": "edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3",
"id": "edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"ip_restriction": null,
"match": "/",
"match_type": "path_prefix",
"metadata": "{\"environment\": \"staging\"}",
"oauth": null,
"oidc": null,
"policy": null,
"request_headers": null,
"response_headers": null,
"saml": null,
"uri": "https://api.ngrok.com/edges/https/edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3/routes/edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}

Fields

NameTypeDescription
edge_idstringunique identifier of this edge
idstringunique identifier of this edge route
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
match_typestringType of match to use for this route. Valid values are "exact_path" and "path_prefix".
matchstringRoute selector: "/blog" or "example.com" or "example.com/blog"
uristringURI of the edge API resource
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
backendEndpointBackendbackend module configuration or null
ip_restrictionEndpointIPPolicyip restriction module configuration or null
circuit_breakerEndpointCircuitBreakercircuit breaker module configuration or null
compressionEndpointCompressioncompression module configuration or null
request_headersEndpointRequestHeadersrequest headers module configuration or null
response_headersEndpointResponseHeadersresponse headers module configuration or null
webhook_verificationEndpointWebhookValidationwebhook verification module configuration or null
oauthEndpointOAuthoauth module configuration or null
samlEndpointSAMLsaml module configuration or null
oidcEndpointOIDCoidc module configuration or null
websocket_tcp_converterEndpointWebsocketTCPConverterwebsocket to tcp adapter configuration or null
user_agent_filterEndpointUserAgentFilter
policyEndpointPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointCircuitBreaker fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
tripped_durationuint32Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_windowuint32Integer number of seconds in the statistical rolling window that metrics are retained for.
num_bucketsuint32Integer number of buckets into which metrics are retained. Max 128.
volume_thresholduint32Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentagefloat64Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields

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

EndpointRequestHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<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
removeList<string>a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<string, string>a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
removeList<string>a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointWebhookValidation fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerstringa string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification
secretstringa string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerEndpointOAuthProvideran object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_intervaluint32Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider fields

NameTypeDescription
githubEndpointOAuthGitHubconfiguration for using github as the identity provider
facebookEndpointOAuthFacebookconfiguration for using facebook as the identity provider
microsoftEndpointOAuthMicrosoftconfiguration for using microsoft as the identity provider
googleEndpointOAuthGoogleconfiguration for using google as the identity provider
linkedinEndpointOAuthLinkedInconfiguration for using linkedin as the identity provider
gitlabEndpointOAuthGitLabconfiguration for using gitlab as the identity provider
twitchEndpointOAuthTwitchconfiguration for using twitch as the identity provider
amazonEndpointOAuthAmazonconfiguration for using amazon as the identity provider

EndpointOAuthGitHub fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teamsList<string>a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizationsList<string>a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthGitLab fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthTwitch fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthAmazon fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointSAML fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadatastringThe full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authnbooleanIf 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_initiatedbooleanIf true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groupsList<string>If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_idstringThe 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_urlstringThe 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_urlstringThe 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_pemstringPEM-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_urlstringA 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_formatstringDefines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuerstringURL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_idstringThe OIDC app's client ID and OIDC audience.
client_secretstringThe OIDC app's client secret.
scopesList<string>The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

EndpointUserAgentFilter fields

NameTypeDescription
enabledboolean
allowList<string>
denyList<string>

EndpointPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
inboundEndpointRulethe inbound rules of the traffic policy.
outboundEndpointRulethe outbound rules on the traffic policy.

EndpointRule fields

NameTypeDescription
expressionsList<string>cel expressions that filter traffic the policy rule applies to.
actionsEndpointActionthe set of actions on a policy rule.
namestringthe name of the rule that is part of the traffic policy.

EndpointAction fields

NameTypeDescription
typestringthe type of action on the policy rule.
configobjectthe configuration for the action on the policy rule.

Update HTTPS Edge Route

Updates an HTTPS Edge Route by ID. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.

Request

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

Example Request

curl \
-X PATCH \
-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_2cSjzEXC8I8IehdZ1edZFDzPfR3/routes/edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP

Parameters

NameTypeDescription
edge_idstringunique identifier of this edge
idstringunique identifier of this edge route
match_typestringType of match to use for this route. Valid values are "exact_path" and "path_prefix".
matchstringRoute selector: "/blog" or "example.com" or "example.com/blog"
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
backendEndpointBackendMutatebackend module configuration or null
ip_restrictionEndpointIPPolicyMutateip restriction module configuration or null
circuit_breakerEndpointCircuitBreakercircuit breaker module configuration or null
compressionEndpointCompressioncompression module configuration or null
request_headersEndpointRequestHeadersrequest headers module configuration or null
response_headersEndpointResponseHeadersresponse headers module configuration or null
webhook_verificationEndpointWebhookValidationwebhook verification module configuration or null
oauthEndpointOAuthoauth module configuration or null
samlEndpointSAMLMutatesaml module configuration or null
oidcEndpointOIDCoidc module configuration or null
websocket_tcp_converterEndpointWebsocketTCPConverterwebsocket to tcp adapter configuration or null
user_agent_filterEndpointUserAgentFilter
policyEndpointPolicythe traffic policy associated with this edge or null

EndpointBackendMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backend_idstringbackend to be used to back this endpoint

EndpointIPPolicyMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policy_idsList<string>list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointCircuitBreaker parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
tripped_durationuint32Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_windowuint32Integer number of seconds in the statistical rolling window that metrics are retained for.
num_bucketsuint32Integer number of buckets into which metrics are retained. Max 128.
volume_thresholduint32Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentagefloat64Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression parameters

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

EndpointRequestHeaders parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<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
removeList<string>a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<string, string>a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
removeList<string>a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointWebhookValidation parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerstringa string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification
secretstringa string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerEndpointOAuthProvideran object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_intervaluint32Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider parameters

NameTypeDescription
githubEndpointOAuthGitHubconfiguration for using github as the identity provider
facebookEndpointOAuthFacebookconfiguration for using facebook as the identity provider
microsoftEndpointOAuthMicrosoftconfiguration for using microsoft as the identity provider
googleEndpointOAuthGoogleconfiguration for using google as the identity provider
linkedinEndpointOAuthLinkedInconfiguration for using linkedin as the identity provider
gitlabEndpointOAuthGitLabconfiguration for using gitlab as the identity provider
twitchEndpointOAuthTwitchconfiguration for using twitch as the identity provider
amazonEndpointOAuthAmazonconfiguration for using amazon as the identity provider

EndpointOAuthGitHub parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teamsList<string>a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizationsList<string>a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthGitLab parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthTwitch parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthAmazon parameters

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointSAMLMutate parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadatastringThe full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authnbooleanIf 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_initiatedbooleanIf true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groupsList<string>If present, only users who are a member of one of the listed groups may access the target endpoint.
nameid_formatstringDefines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuerstringURL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_idstringThe OIDC app's client ID and OIDC audience.
client_secretstringThe OIDC app's client secret.
scopesList<string>The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter parameters

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

EndpointUserAgentFilter parameters

NameTypeDescription
enabledboolean
allowList<string>
denyList<string>

EndpointPolicy parameters

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
inboundEndpointRulethe inbound rules of the traffic policy.
outboundEndpointRulethe outbound rules on the traffic policy.

EndpointRule parameters

NameTypeDescription
expressionsList<string>cel expressions that filter traffic the policy rule applies to.
actionsEndpointActionthe set of actions on a policy rule.
namestringthe name of the rule that is part of the traffic policy.

EndpointAction parameters

NameTypeDescription
typestringthe type of action on the policy rule.
configobjectthe configuration for the action on the policy rule.

Response

Returns a 200 response on success

Example Response

{
"backend": null,
"circuit_breaker": null,
"compression": null,
"created_at": "2024-02-16T19:35:33Z",
"edge_id": "edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3",
"id": "edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"ip_restriction": null,
"match": "/",
"match_type": "path_prefix",
"metadata": "{\"environment\": \"production\"}",
"oauth": null,
"oidc": null,
"policy": null,
"request_headers": null,
"response_headers": null,
"saml": null,
"uri": "https://api.ngrok.com/edges/https/edghts_2cSjzEXC8I8IehdZ1edZFDzPfR3/routes/edghtsrt_2cSjzAGwqaoOicXsq3ka49UVQNP",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}

Fields

NameTypeDescription
edge_idstringunique identifier of this edge
idstringunique identifier of this edge route
created_atstringtimestamp when the edge configuration was created, RFC 3339 format
match_typestringType of match to use for this route. Valid values are "exact_path" and "path_prefix".
matchstringRoute selector: "/blog" or "example.com" or "example.com/blog"
uristringURI of the edge API resource
descriptionstringhuman-readable description of what this edge will be used for; optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
backendEndpointBackendbackend module configuration or null
ip_restrictionEndpointIPPolicyip restriction module configuration or null
circuit_breakerEndpointCircuitBreakercircuit breaker module configuration or null
compressionEndpointCompressioncompression module configuration or null
request_headersEndpointRequestHeadersrequest headers module configuration or null
response_headersEndpointResponseHeadersresponse headers module configuration or null
webhook_verificationEndpointWebhookValidationwebhook verification module configuration or null
oauthEndpointOAuthoauth module configuration or null
samlEndpointSAMLsaml module configuration or null
oidcEndpointOIDCoidc module configuration or null
websocket_tcp_converterEndpointWebsocketTCPConverterwebsocket to tcp adapter configuration or null
user_agent_filterEndpointUserAgentFilter
policyEndpointPolicythe traffic policy associated with this edge or null

EndpointBackend fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
backendRefbackend to be used to back this endpoint

Ref fields

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

EndpointIPPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
ip_policiesReflist of all IP policies that will be used to check if a source IP is allowed access to the endpoint

EndpointCircuitBreaker fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
tripped_durationuint32Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_windowuint32Integer number of seconds in the statistical rolling window that metrics are retained for.
num_bucketsuint32Integer number of buckets into which metrics are retained. Max 128.
volume_thresholduint32Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentagefloat64Error threshold percentage should be between 0 - 1.0, not 0-100.0

EndpointCompression fields

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

EndpointRequestHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<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
removeList<string>a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

EndpointResponseHeaders fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
addMap<string, string>a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
removeList<string>a list of header names that will be removed from the HTTP Response returned to the HTTP client

EndpointWebhookValidation fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerstringa string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification
secretstringa string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

EndpointOAuth fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
providerEndpointOAuthProvideran object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_intervaluint32Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider fields

NameTypeDescription
githubEndpointOAuthGitHubconfiguration for using github as the identity provider
facebookEndpointOAuthFacebookconfiguration for using facebook as the identity provider
microsoftEndpointOAuthMicrosoftconfiguration for using microsoft as the identity provider
googleEndpointOAuthGoogleconfiguration for using google as the identity provider
linkedinEndpointOAuthLinkedInconfiguration for using linkedin as the identity provider
gitlabEndpointOAuthGitLabconfiguration for using gitlab as the identity provider
twitchEndpointOAuthTwitchconfiguration for using twitch as the identity provider
amazonEndpointOAuthAmazonconfiguration for using amazon as the identity provider

EndpointOAuthGitHub fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teamsList<string>a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizationsList<string>a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields

NameTypeDescription
client_idstringthe 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_secretstringthe OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopesList<string>a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addressesList<string>a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domainsList<string>a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthGitLab fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthTwitch fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointOAuthAmazon fields

NameTypeDescription
client_idstring
client_secretstring
scopesList<string>
email_addressesList<string>
email_domainsList<string>

EndpointSAML fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadatastringThe full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
force_authnbooleanIf 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_initiatedbooleanIf true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groupsList<string>If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_idstringThe 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_urlstringThe 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_urlstringThe 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_pemstringPEM-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_urlstringA 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_formatstringDefines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

EndpointOIDC fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
options_passthroughbooleanDo not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefixstringthe prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeoutuint32Integer 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_durationuint32Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuerstringURL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_idstringThe OIDC app's client ID and OIDC audience.
client_secretstringThe OIDC app's client secret.
scopesList<string>The set of scopes to request from the OIDC identity provider.

EndpointWebsocketTCPConverter fields

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

EndpointUserAgentFilter fields

NameTypeDescription
enabledboolean
allowList<string>
denyList<string>

EndpointPolicy fields

NameTypeDescription
enabledbooleantrue if the module will be applied to traffic, false to disable. default true if unspecified
inboundEndpointRulethe inbound rules of the traffic policy.
outboundEndpointRulethe outbound rules on the traffic policy.

EndpointRule fields

NameTypeDescription
expressionsList<string>cel expressions that filter traffic the policy rule applies to.
actionsEndpointActionthe set of actions on a policy rule.
namestringthe name of the rule that is part of the traffic policy.

EndpointAction fields

NameTypeDescription
typestringthe type of action on the policy rule.
configobjectthe configuration for the action on the policy rule.

Delete HTTPS Edge Route

Delete an HTTPS Edge Route by ID

Request

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

Example Request

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

Response

Returns a 204 response with no body on success