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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes
Parameters
Name | Type | Description |
---|---|---|
edge_id | string | unique identifier of this edge |
match_type | string | Type of match to use for this route. Valid values are "exact_path" and "path_prefix". |
match | string | Route selector: "/blog" or "example.com" or "example.com/blog" |
description | string | human-readable description of what this edge will be used for; optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. |
backend | EndpointBackendMutate | backend module configuration or null |
ip_restriction | EndpointIPPolicyMutate | ip restriction module configuration or null |
circuit_breaker | EndpointCircuitBreaker | circuit breaker module configuration or null |
compression | EndpointCompression | compression module configuration or null |
request_headers | EndpointRequestHeaders | request headers module configuration or null |
response_headers | EndpointResponseHeaders | response headers module configuration or null |
webhook_verification | EndpointWebhookValidation | webhook verification module configuration or null |
oauth | EndpointOAuth | oauth module configuration or null |
saml | EndpointSAMLMutate | saml module configuration or null |
oidc | EndpointOIDC | oidc module configuration or null |
websocket_tcp_converter | EndpointWebsocketTCPConverter | websocket to tcp adapter configuration or null |
user_agent_filter | EndpointUserAgentFilter | |
policy | EndpointPolicy | the traffic policy associated with this edge or null |
EndpointBackendMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
backend_id | string | backend to be used to back this endpoint |
EndpointIPPolicyMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
ip_policy_ids | List<string> | list of all IP policies that will be used to check if a source IP is allowed access to the endpoint |
EndpointCircuitBreaker parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
tripped_duration | uint32 | Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health |
rolling_window | uint32 | Integer number of seconds in the statistical rolling window that metrics are retained for. |
num_buckets | uint32 | Integer number of buckets into which metrics are retained. Max 128. |
volume_threshold | uint32 | Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. |
error_threshold_percentage | float64 | Error threshold percentage should be between 0 - 1.0, not 0-100.0 |
EndpointCompression parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointRequestHeaders parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server |
remove | List<string> | a list of header names that will be removed from the HTTP Request before being sent to the upstream application server |
EndpointResponseHeaders parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client |
remove | List<string> | a list of header names that will be removed from the HTTP Response returned to the HTTP client |
EndpointWebhookValidation parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | string | a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification |
secret | string | a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
EndpointOAuth parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | EndpointOAuthProvider | an object which defines the identity provider to use for authentication and configuration for who may access the endpoint |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
auth_check_interval | uint32 | Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource. |
EndpointOAuthProvider parameters
Name | Type | Description |
---|---|---|
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 |
linkedin | EndpointOAuthLinkedIn | configuration for using linkedin as the identity provider |
gitlab | EndpointOAuthGitLab | configuration for using gitlab as the identity provider |
twitch | EndpointOAuthTwitch | configuration for using twitch as the identity provider |
amazon | EndpointOAuthAmazon | configuration for using amazon as the identity provider |
EndpointOAuthGitHub parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
teams | List<string> | a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name |
organizations | List<string> | a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug' |
EndpointOAuthFacebook parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthMicrosoft parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthGoogle parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthLinkedIn parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthGitLab parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthTwitch parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthAmazon parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointSAMLMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
idp_metadata | string | The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. |
force_authn | boolean | If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP. |
allow_idp_initiated | boolean | If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed. |
authorized_groups | List<string> | If present, only users who are a member of one of the listed groups may access the target endpoint. |
nameid_format | string | Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported. |
EndpointOIDC parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
issuer | string | URL of the OIDC "OpenID provider". This is the base URL used for discovery. |
client_id | string | The OIDC app's client ID and OIDC audience. |
client_secret | string | The OIDC app's client secret. |
scopes | List<string> | The set of scopes to request from the OIDC identity provider. |
EndpointWebsocketTCPConverter parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointUserAgentFilter parameters
Name | Type | Description |
---|---|---|
enabled | boolean | |
allow | List<string> | |
deny | List<string> |
EndpointPolicy parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
inbound | EndpointRule | the inbound rules of the traffic policy. |
outbound | EndpointRule | the outbound rules on the traffic policy. |
EndpointRule parameters
Name | Type | Description |
---|---|---|
expressions | List<string> | cel expressions that filter traffic the policy rule applies to. |
actions | EndpointAction | the set of actions on a policy rule. |
name | string | the name of the rule that is part of the traffic policy. |
EndpointAction parameters
Name | Type | Description |
---|---|---|
type | string | the type of action on the policy rule. |
config | object | the 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-05-23T20:36:23Z",
"description": "acme edge route",
"edge_id": "edghts_2gsqMMMcbwCFaW2NOcg1tRZkQyX",
"id": "edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}
Fields
Name | Type | Description |
---|---|---|
edge_id | string | unique identifier of this edge |
id | string | unique identifier of this edge route |
created_at | string | timestamp when the edge configuration was created, RFC 3339 format |
match_type | string | Type of match to use for this route. Valid values are "exact_path" and "path_prefix". |
match | string | Route selector: "/blog" or "example.com" or "example.com/blog" |
uri | string | URI of the edge API resource |
description | string | human-readable description of what this edge will be used for; optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. |
backend | EndpointBackend | backend module configuration or null |
ip_restriction | EndpointIPPolicy | ip restriction module configuration or null |
circuit_breaker | EndpointCircuitBreaker | circuit breaker module configuration or null |
compression | EndpointCompression | compression module configuration or null |
request_headers | EndpointRequestHeaders | request headers module configuration or null |
response_headers | EndpointResponseHeaders | response headers module configuration or null |
webhook_verification | EndpointWebhookValidation | webhook verification module configuration or null |
oauth | EndpointOAuth | oauth module configuration or null |
saml | EndpointSAML | saml module configuration or null |
oidc | EndpointOIDC | oidc module configuration or null |
websocket_tcp_converter | EndpointWebsocketTCPConverter | websocket to tcp adapter configuration or null |
user_agent_filter | EndpointUserAgentFilter | |
policy | EndpointPolicy | the traffic policy associated with this edge or null |
EndpointBackend fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
backend | Ref | backend to be used to back this endpoint |
Ref fields
Name | Type | Description |
---|---|---|
id | string | a resource identifier |
uri | string | a uri for locating a resource |
EndpointIPPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
ip_policies | Ref | list of all IP policies that will be used to check if a source IP is allowed access to the endpoint |
EndpointCircuitBreaker fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
tripped_duration | uint32 | Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health |
rolling_window | uint32 | Integer number of seconds in the statistical rolling window that metrics are retained for. |
num_buckets | uint32 | Integer number of buckets into which metrics are retained. Max 128. |
volume_threshold | uint32 | Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. |
error_threshold_percentage | float64 | Error threshold percentage should be between 0 - 1.0, not 0-100.0 |
EndpointCompression fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointRequestHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server |
remove | List<string> | a list of header names that will be removed from the HTTP Request before being sent to the upstream application server |
EndpointResponseHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client |
remove | List<string> | a list of header names that will be removed from the HTTP Response returned to the HTTP client |
EndpointWebhookValidation fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | string | a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification |
secret | string | a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
EndpointOAuth fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | EndpointOAuthProvider | an object which defines the identity provider to use for authentication and configuration for who may access the endpoint |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
auth_check_interval | uint32 | Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource. |
EndpointOAuthProvider fields
Name | Type | Description |
---|---|---|
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 |
linkedin | EndpointOAuthLinkedIn | configuration for using linkedin as the identity provider |
gitlab | EndpointOAuthGitLab | configuration for using gitlab as the identity provider |
twitch | EndpointOAuthTwitch | configuration for using twitch as the identity provider |
amazon | EndpointOAuthAmazon | configuration for using amazon as the identity provider |
EndpointOAuthGitHub fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
teams | List<string> | a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name |
organizations | List<string> | a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug' |
EndpointOAuthFacebook fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthMicrosoft fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthGoogle fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthLinkedIn fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthGitLab fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthTwitch fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthAmazon fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointSAML fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
idp_metadata | string | The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. |
force_authn | boolean | If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP. |
allow_idp_initiated | boolean | If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed. |
authorized_groups | List<string> | If present, only users who are a member of one of the listed groups may access the target endpoint. |
entity_id | string | The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration. |
assertion_consumer_service_url | string | The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration. |
single_logout_url | string | The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration. |
request_signing_certificate_pem | string | PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported. |
metadata_url | string | A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata. |
nameid_format | string | Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported. |
EndpointOIDC fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
issuer | string | URL of the OIDC "OpenID provider". This is the base URL used for discovery. |
client_id | string | The OIDC app's client ID and OIDC audience. |
client_secret | string | The OIDC app's client secret. |
scopes | List<string> | The set of scopes to request from the OIDC identity provider. |
EndpointWebsocketTCPConverter fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointUserAgentFilter fields
Name | Type | Description |
---|---|---|
enabled | boolean | |
allow | List<string> | |
deny | List<string> |
EndpointPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
inbound | EndpointRule | the inbound rules of the traffic policy. |
outbound | EndpointRule | the outbound rules on the traffic policy. |
EndpointRule fields
Name | Type | Description |
---|---|---|
expressions | List<string> | cel expressions that filter traffic the policy rule applies to. |
actions | EndpointAction | the set of actions on a policy rule. |
name | string | the name of the rule that is part of the traffic policy. |
EndpointAction fields
Name | Type | Description |
---|---|---|
type | string | the type of action on the policy rule. |
config | object | the 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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO
Response
Returns a 200 response on success
Example Response
{
"backend": null,
"circuit_breaker": null,
"compression": null,
"created_at": "2024-05-23T20:36:23Z",
"description": "acme edge route",
"edge_id": "edghts_2gsqMMMcbwCFaW2NOcg1tRZkQyX",
"id": "edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}
Fields
Name | Type | Description |
---|---|---|
edge_id | string | unique identifier of this edge |
id | string | unique identifier of this edge route |
created_at | string | timestamp when the edge configuration was created, RFC 3339 format |
match_type | string | Type of match to use for this route. Valid values are "exact_path" and "path_prefix". |
match | string | Route selector: "/blog" or "example.com" or "example.com/blog" |
uri | string | URI of the edge API resource |
description | string | human-readable description of what this edge will be used for; optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. |
backend | EndpointBackend | backend module configuration or null |
ip_restriction | EndpointIPPolicy | ip restriction module configuration or null |
circuit_breaker | EndpointCircuitBreaker | circuit breaker module configuration or null |
compression | EndpointCompression | compression module configuration or null |
request_headers | EndpointRequestHeaders | request headers module configuration or null |
response_headers | EndpointResponseHeaders | response headers module configuration or null |
webhook_verification | EndpointWebhookValidation | webhook verification module configuration or null |
oauth | EndpointOAuth | oauth module configuration or null |
saml | EndpointSAML | saml module configuration or null |
oidc | EndpointOIDC | oidc module configuration or null |
websocket_tcp_converter | EndpointWebsocketTCPConverter | websocket to tcp adapter configuration or null |
user_agent_filter | EndpointUserAgentFilter | |
policy | EndpointPolicy | the traffic policy associated with this edge or null |
EndpointBackend fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
backend | Ref | backend to be used to back this endpoint |
Ref fields
Name | Type | Description |
---|---|---|
id | string | a resource identifier |
uri | string | a uri for locating a resource |
EndpointIPPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
ip_policies | Ref | list of all IP policies that will be used to check if a source IP is allowed access to the endpoint |
EndpointCircuitBreaker fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
tripped_duration | uint32 | Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health |
rolling_window | uint32 | Integer number of seconds in the statistical rolling window that metrics are retained for. |
num_buckets | uint32 | Integer number of buckets into which metrics are retained. Max 128. |
volume_threshold | uint32 | Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. |
error_threshold_percentage | float64 | Error threshold percentage should be between 0 - 1.0, not 0-100.0 |
EndpointCompression fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointRequestHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server |
remove | List<string> | a list of header names that will be removed from the HTTP Request before being sent to the upstream application server |
EndpointResponseHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client |
remove | List<string> | a list of header names that will be removed from the HTTP Response returned to the HTTP client |
EndpointWebhookValidation fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | string | a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification |
secret | string | a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
EndpointOAuth fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | EndpointOAuthProvider | an object which defines the identity provider to use for authentication and configuration for who may access the endpoint |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
auth_check_interval | uint32 | Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource. |
EndpointOAuthProvider fields
Name | Type | Description |
---|---|---|
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 |
linkedin | EndpointOAuthLinkedIn | configuration for using linkedin as the identity provider |
gitlab | EndpointOAuthGitLab | configuration for using gitlab as the identity provider |
twitch | EndpointOAuthTwitch | configuration for using twitch as the identity provider |
amazon | EndpointOAuthAmazon | configuration for using amazon as the identity provider |
EndpointOAuthGitHub fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
teams | List<string> | a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name |
organizations | List<string> | a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug' |
EndpointOAuthFacebook fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthMicrosoft fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthGoogle fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthLinkedIn fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthGitLab fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthTwitch fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthAmazon fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointSAML fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
idp_metadata | string | The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. |
force_authn | boolean | If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP. |
allow_idp_initiated | boolean | If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed. |
authorized_groups | List<string> | If present, only users who are a member of one of the listed groups may access the target endpoint. |
entity_id | string | The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration. |
assertion_consumer_service_url | string | The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration. |
single_logout_url | string | The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration. |
request_signing_certificate_pem | string | PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported. |
metadata_url | string | A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata. |
nameid_format | string | Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported. |
EndpointOIDC fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
issuer | string | URL of the OIDC "OpenID provider". This is the base URL used for discovery. |
client_id | string | The OIDC app's client ID and OIDC audience. |
client_secret | string | The OIDC app's client secret. |
scopes | List<string> | The set of scopes to request from the OIDC identity provider. |
EndpointWebsocketTCPConverter fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointUserAgentFilter fields
Name | Type | Description |
---|---|---|
enabled | boolean | |
allow | List<string> | |
deny | List<string> |
EndpointPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
inbound | EndpointRule | the inbound rules of the traffic policy. |
outbound | EndpointRule | the outbound rules on the traffic policy. |
EndpointRule fields
Name | Type | Description |
---|---|---|
expressions | List<string> | cel expressions that filter traffic the policy rule applies to. |
actions | EndpointAction | the set of actions on a policy rule. |
name | string | the name of the rule that is part of the traffic policy. |
EndpointAction fields
Name | Type | Description |
---|---|---|
type | string | the type of action on the policy rule. |
config | object | the 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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO
Parameters
Name | Type | Description |
---|---|---|
edge_id | string | unique identifier of this edge |
id | string | unique identifier of this edge route |
match_type | string | Type of match to use for this route. Valid values are "exact_path" and "path_prefix". |
match | string | Route selector: "/blog" or "example.com" or "example.com/blog" |
description | string | human-readable description of what this edge will be used for; optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. |
backend | EndpointBackendMutate | backend module configuration or null |
ip_restriction | EndpointIPPolicyMutate | ip restriction module configuration or null |
circuit_breaker | EndpointCircuitBreaker | circuit breaker module configuration or null |
compression | EndpointCompression | compression module configuration or null |
request_headers | EndpointRequestHeaders | request headers module configuration or null |
response_headers | EndpointResponseHeaders | response headers module configuration or null |
webhook_verification | EndpointWebhookValidation | webhook verification module configuration or null |
oauth | EndpointOAuth | oauth module configuration or null |
saml | EndpointSAMLMutate | saml module configuration or null |
oidc | EndpointOIDC | oidc module configuration or null |
websocket_tcp_converter | EndpointWebsocketTCPConverter | websocket to tcp adapter configuration or null |
user_agent_filter | EndpointUserAgentFilter | |
policy | EndpointPolicy | the traffic policy associated with this edge or null |
EndpointBackendMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
backend_id | string | backend to be used to back this endpoint |
EndpointIPPolicyMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
ip_policy_ids | List<string> | list of all IP policies that will be used to check if a source IP is allowed access to the endpoint |
EndpointCircuitBreaker parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
tripped_duration | uint32 | Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health |
rolling_window | uint32 | Integer number of seconds in the statistical rolling window that metrics are retained for. |
num_buckets | uint32 | Integer number of buckets into which metrics are retained. Max 128. |
volume_threshold | uint32 | Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. |
error_threshold_percentage | float64 | Error threshold percentage should be between 0 - 1.0, not 0-100.0 |
EndpointCompression parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointRequestHeaders parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server |
remove | List<string> | a list of header names that will be removed from the HTTP Request before being sent to the upstream application server |
EndpointResponseHeaders parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client |
remove | List<string> | a list of header names that will be removed from the HTTP Response returned to the HTTP client |
EndpointWebhookValidation parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | string | a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification |
secret | string | a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
EndpointOAuth parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | EndpointOAuthProvider | an object which defines the identity provider to use for authentication and configuration for who may access the endpoint |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
auth_check_interval | uint32 | Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource. |
EndpointOAuthProvider parameters
Name | Type | Description |
---|---|---|
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 |
linkedin | EndpointOAuthLinkedIn | configuration for using linkedin as the identity provider |
gitlab | EndpointOAuthGitLab | configuration for using gitlab as the identity provider |
twitch | EndpointOAuthTwitch | configuration for using twitch as the identity provider |
amazon | EndpointOAuthAmazon | configuration for using amazon as the identity provider |
EndpointOAuthGitHub parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
teams | List<string> | a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name |
organizations | List<string> | a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug' |
EndpointOAuthFacebook parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthMicrosoft parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthGoogle parameters
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthLinkedIn parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthGitLab parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthTwitch parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthAmazon parameters
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointSAMLMutate parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
idp_metadata | string | The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. |
force_authn | boolean | If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP. |
allow_idp_initiated | boolean | If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed. |
authorized_groups | List<string> | If present, only users who are a member of one of the listed groups may access the target endpoint. |
nameid_format | string | Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported. |
EndpointOIDC parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
issuer | string | URL of the OIDC "OpenID provider". This is the base URL used for discovery. |
client_id | string | The OIDC app's client ID and OIDC audience. |
client_secret | string | The OIDC app's client secret. |
scopes | List<string> | The set of scopes to request from the OIDC identity provider. |
EndpointWebsocketTCPConverter parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointUserAgentFilter parameters
Name | Type | Description |
---|---|---|
enabled | boolean | |
allow | List<string> | |
deny | List<string> |
EndpointPolicy parameters
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
inbound | EndpointRule | the inbound rules of the traffic policy. |
outbound | EndpointRule | the outbound rules on the traffic policy. |
EndpointRule parameters
Name | Type | Description |
---|---|---|
expressions | List<string> | cel expressions that filter traffic the policy rule applies to. |
actions | EndpointAction | the set of actions on a policy rule. |
name | string | the name of the rule that is part of the traffic policy. |
EndpointAction parameters
Name | Type | Description |
---|---|---|
type | string | the type of action on the policy rule. |
config | object | the 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-05-23T20:36:23Z",
"edge_id": "edghts_2gsqMMMcbwCFaW2NOcg1tRZkQyX",
"id": "edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO",
"user_agent_filter": null,
"webhook_verification": null,
"websocket_tcp_converter": null
}
Fields
Name | Type | Description |
---|---|---|
edge_id | string | unique identifier of this edge |
id | string | unique identifier of this edge route |
created_at | string | timestamp when the edge configuration was created, RFC 3339 format |
match_type | string | Type of match to use for this route. Valid values are "exact_path" and "path_prefix". |
match | string | Route selector: "/blog" or "example.com" or "example.com/blog" |
uri | string | URI of the edge API resource |
description | string | human-readable description of what this edge will be used for; optional, max 255 bytes. |
metadata | string | arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. |
backend | EndpointBackend | backend module configuration or null |
ip_restriction | EndpointIPPolicy | ip restriction module configuration or null |
circuit_breaker | EndpointCircuitBreaker | circuit breaker module configuration or null |
compression | EndpointCompression | compression module configuration or null |
request_headers | EndpointRequestHeaders | request headers module configuration or null |
response_headers | EndpointResponseHeaders | response headers module configuration or null |
webhook_verification | EndpointWebhookValidation | webhook verification module configuration or null |
oauth | EndpointOAuth | oauth module configuration or null |
saml | EndpointSAML | saml module configuration or null |
oidc | EndpointOIDC | oidc module configuration or null |
websocket_tcp_converter | EndpointWebsocketTCPConverter | websocket to tcp adapter configuration or null |
user_agent_filter | EndpointUserAgentFilter | |
policy | EndpointPolicy | the traffic policy associated with this edge or null |
EndpointBackend fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
backend | Ref | backend to be used to back this endpoint |
Ref fields
Name | Type | Description |
---|---|---|
id | string | a resource identifier |
uri | string | a uri for locating a resource |
EndpointIPPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
ip_policies | Ref | list of all IP policies that will be used to check if a source IP is allowed access to the endpoint |
EndpointCircuitBreaker fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
tripped_duration | uint32 | Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health |
rolling_window | uint32 | Integer number of seconds in the statistical rolling window that metrics are retained for. |
num_buckets | uint32 | Integer number of buckets into which metrics are retained. Max 128. |
volume_threshold | uint32 | Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. |
error_threshold_percentage | float64 | Error threshold percentage should be between 0 - 1.0, not 0-100.0 |
EndpointCompression fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointRequestHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server |
remove | List<string> | a list of header names that will be removed from the HTTP Request before being sent to the upstream application server |
EndpointResponseHeaders fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
add | Map<string, string> | a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client |
remove | List<string> | a list of header names that will be removed from the HTTP Response returned to the HTTP client |
EndpointWebhookValidation fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | string | a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification |
secret | string | a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret |
EndpointOAuth fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
provider | EndpointOAuthProvider | an object which defines the identity provider to use for authentication and configuration for who may access the endpoint |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
auth_check_interval | uint32 | Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource. |
EndpointOAuthProvider fields
Name | Type | Description |
---|---|---|
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 |
linkedin | EndpointOAuthLinkedIn | configuration for using linkedin as the identity provider |
gitlab | EndpointOAuthGitLab | configuration for using gitlab as the identity provider |
twitch | EndpointOAuthTwitch | configuration for using twitch as the identity provider |
amazon | EndpointOAuthAmazon | configuration for using amazon as the identity provider |
EndpointOAuthGitHub fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
teams | List<string> | a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name |
organizations | List<string> | a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug' |
EndpointOAuthFacebook fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthMicrosoft fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthGoogle fields
Name | Type | Description |
---|---|---|
client_id | string | the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well. |
client_secret | string | the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id . |
scopes | List<string> | a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes) |
email_addresses | List<string> | a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint |
email_domains | List<string> | a list of email domains of users authenticated by identity provider who are allowed access to the endpoint |
EndpointOAuthLinkedIn fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthGitLab fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthTwitch fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointOAuthAmazon fields
Name | Type | Description |
---|---|---|
client_id | string | |
client_secret | string | |
scopes | List<string> | |
email_addresses | List<string> | |
email_domains | List<string> |
EndpointSAML fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
idp_metadata | string | The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. |
force_authn | boolean | If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP. |
allow_idp_initiated | boolean | If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed. |
authorized_groups | List<string> | If present, only users who are a member of one of the listed groups may access the target endpoint. |
entity_id | string | The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration. |
assertion_consumer_service_url | string | The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration. |
single_logout_url | string | The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration. |
request_signing_certificate_pem | string | PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported. |
metadata_url | string | A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata. |
nameid_format | string | Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported. |
EndpointOIDC fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
options_passthrough | boolean | Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. |
cookie_prefix | string | the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' |
inactivity_timeout | uint32 | Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate. |
maximum_duration | uint32 | Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. |
issuer | string | URL of the OIDC "OpenID provider". This is the base URL used for discovery. |
client_id | string | The OIDC app's client ID and OIDC audience. |
client_secret | string | The OIDC app's client secret. |
scopes | List<string> | The set of scopes to request from the OIDC identity provider. |
EndpointWebsocketTCPConverter fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
EndpointUserAgentFilter fields
Name | Type | Description |
---|---|---|
enabled | boolean | |
allow | List<string> | |
deny | List<string> |
EndpointPolicy fields
Name | Type | Description |
---|---|---|
enabled | boolean | true if the module will be applied to traffic, false to disable. default true if unspecified |
inbound | EndpointRule | the inbound rules of the traffic policy. |
outbound | EndpointRule | the outbound rules on the traffic policy. |
EndpointRule fields
Name | Type | Description |
---|---|---|
expressions | List<string> | cel expressions that filter traffic the policy rule applies to. |
actions | EndpointAction | the set of actions on a policy rule. |
name | string | the name of the rule that is part of the traffic policy. |
EndpointAction fields
Name | Type | Description |
---|---|---|
type | string | the type of action on the policy rule. |
config | object | the 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_2gsqMMMcbwCFaW2NOcg1tRZkQyX/routes/edghtsrt_2gsqMPZEeSTVp5vEewt1FfvvosO
Response
Returns a 204 response with no body on success