> ## Documentation Index > Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create > Create an HTTPS Edge Route ## OpenAPI ````yaml https://raw.githubusercontent.com/ngrok/ngrok-openapi/refs/heads/main/ngrok.yaml post /edges/https/{edge_id}/routes openapi: 3.0.0 info: title: ngrok OpenAPI version: 1.0.0 servers: - url: https://api.ngrok.com security: - authentication: [] paths: /edges/https/{edge_id}/routes: post: tags: - EdgesHTTPSRoutes summary: Create description: | Create an HTTPS Edge Route operationId: EdgesHttpsRoutesCreate parameters: - $ref: '#/components/parameters/ngrokVersion' - name: edge_id description: | unique identifier of this edge in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/HTTPSEdgeRouteCreate' responses: '201': description: | Create an HTTPS Edge Route content: application/json: schema: $ref: '#/components/schemas/HTTPSEdgeRoute' components: parameters: ngrokVersion: name: ngrok-version in: header required: true schema: type: integer default: 2 schemas: HTTPSEdgeRouteCreate: type: object required: - match_type - match properties: edge_id: description: | unique identifier of this edge type: string match_type: description: > Type of match to use for this route. Valid values are "exact_path" and "path_prefix". type: string match: description: | Route selector: "/blog" or "example.com" or "example.com/blog" type: string description: description: > human-readable description of what this edge will be used for; optional, max 255 bytes. type: string metadata: description: > arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. type: string backend: $ref: '#/components/schemas/EndpointBackendMutate' description: | backend module configuration or `null` ip_restriction: $ref: '#/components/schemas/EndpointIPPolicyMutate' description: | ip restriction module configuration or `null` circuit_breaker: $ref: '#/components/schemas/EndpointCircuitBreaker' description: | circuit breaker module configuration or `null` compression: $ref: '#/components/schemas/EndpointCompression' description: | compression module configuration or `null` request_headers: $ref: '#/components/schemas/EndpointRequestHeaders' description: | request headers module configuration or `null` response_headers: $ref: '#/components/schemas/EndpointResponseHeaders' description: | response headers module configuration or `null` webhook_verification: $ref: '#/components/schemas/EndpointWebhookValidation' description: | webhook verification module configuration or `null` oauth: $ref: '#/components/schemas/EndpointOAuth' description: | oauth module configuration or `null` saml: $ref: '#/components/schemas/EndpointSAMLMutate' description: | saml module configuration or `null` oidc: $ref: '#/components/schemas/EndpointOIDC' description: | oidc module configuration or `null` websocket_tcp_converter: $ref: '#/components/schemas/EndpointWebsocketTCPConverter' description: | websocket to tcp adapter configuration or `null` user_agent_filter: $ref: '#/components/schemas/EndpointUserAgentFilter' description: n/a traffic_policy: $ref: '#/components/schemas/EndpointTrafficPolicy' description: | the traffic policy associated with this edge or null HTTPSEdgeRoute: type: object properties: edge_id: description: | unique identifier of this edge type: string id: description: | unique identifier of this edge route type: string created_at: description: | timestamp when the edge configuration was created, RFC 3339 format type: string match_type: description: > Type of match to use for this route. Valid values are "exact_path" and "path_prefix". type: string match: description: | Route selector: "/blog" or "example.com" or "example.com/blog" type: string uri: description: | URI of the edge API resource type: string description: description: > human-readable description of what this edge will be used for; optional, max 255 bytes. type: string metadata: description: > arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes. type: string backend: $ref: '#/components/schemas/EndpointBackend' description: | backend module configuration or `null` ip_restriction: $ref: '#/components/schemas/EndpointIPPolicy' description: | ip restriction module configuration or `null` circuit_breaker: $ref: '#/components/schemas/EndpointCircuitBreaker' description: | circuit breaker module configuration or `null` compression: $ref: '#/components/schemas/EndpointCompression' description: | compression module configuration or `null` request_headers: $ref: '#/components/schemas/EndpointRequestHeaders' description: | request headers module configuration or `null` response_headers: $ref: '#/components/schemas/EndpointResponseHeaders' description: | response headers module configuration or `null` webhook_verification: $ref: '#/components/schemas/EndpointWebhookValidation' description: | webhook verification module configuration or `null` oauth: $ref: '#/components/schemas/EndpointOAuth' description: | oauth module configuration or `null` saml: $ref: '#/components/schemas/EndpointSAML' description: | saml module configuration or `null` oidc: $ref: '#/components/schemas/EndpointOIDC' description: | oidc module configuration or `null` websocket_tcp_converter: $ref: '#/components/schemas/EndpointWebsocketTCPConverter' description: | websocket to tcp adapter configuration or `null` user_agent_filter: $ref: '#/components/schemas/EndpointUserAgentFilter' description: n/a traffic_policy: $ref: '#/components/schemas/EndpointTrafficPolicy' description: | the traffic policy associated with this edge or null EndpointBackendMutate: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean backend_id: description: | backend to be used to back this endpoint type: string EndpointIPPolicyMutate: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean ip_policy_ids: description: > list of all IP policies that will be used to check if a source IP is allowed access to the endpoint type: array items: type: string EndpointCircuitBreaker: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean tripped_duration: description: > Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health type: integer rolling_window: description: > Integer number of seconds in the statistical rolling window that metrics are retained for. type: integer num_buckets: description: | Integer number of buckets into which metrics are retained. Max 128. type: integer volume_threshold: description: > Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low. type: integer error_threshold_percentage: description: | Error threshold percentage should be between 0 - 1.0, not 0-100.0 type: number EndpointCompression: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean EndpointRequestHeaders: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean add: description: > a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server type: object remove: description: > a list of header names that will be removed from the HTTP Request before being sent to the upstream application server type: array items: type: string EndpointResponseHeaders: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean add: description: > a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client type: object remove: description: > a list of header names that will be removed from the HTTP Response returned to the HTTP client type: array items: type: string EndpointWebhookValidation: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean provider: description: > 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 type: string secret: description: > a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret type: string EndpointOAuth: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean provider: $ref: '#/components/schemas/EndpointOAuthProvider' description: > an object which defines the identity provider to use for authentication and configuration for who may access the endpoint options_passthrough: description: > Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. type: boolean cookie_prefix: description: > the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' type: string inactivity_timeout: description: > 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. type: integer maximum_duration: description: > Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. type: integer auth_check_interval: description: > 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. type: integer EndpointSAMLMutate: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean options_passthrough: description: > Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. type: boolean cookie_prefix: description: > the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' type: string inactivity_timeout: description: > 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. type: integer maximum_duration: description: > Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. type: integer idp_metadata: description: > The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. type: string force_authn: description: > 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. type: boolean allow_idp_initiated: description: > 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. type: boolean authorized_groups: description: > If present, only users who are a member of one of the listed groups may access the target endpoint. type: array items: type: string nameid_format: description: > 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. type: string EndpointOIDC: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean options_passthrough: description: > Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. type: boolean cookie_prefix: description: > the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' type: string inactivity_timeout: description: > 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. type: integer maximum_duration: description: > Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. type: integer issuer: description: > URL of the OIDC "OpenID provider". This is the base URL used for discovery. type: string client_id: description: | The OIDC app's client ID and OIDC audience. type: string client_secret: description: | The OIDC app's client secret. type: string scopes: description: | The set of scopes to request from the OIDC identity provider. type: array items: type: string EndpointWebsocketTCPConverter: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean EndpointUserAgentFilter: type: object properties: enabled: description: n/a type: boolean allow: description: n/a type: array items: type: string deny: description: n/a type: array items: type: string EndpointTrafficPolicy: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean value: description: > the traffic policy that should be applied to the traffic on your endpoint. type: string EndpointBackend: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean backend: $ref: '#/components/schemas/Ref' description: | backend to be used to back this endpoint EndpointIPPolicy: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean ip_policies: description: > list of all IP policies that will be used to check if a source IP is allowed access to the endpoint type: array items: $ref: '#/components/schemas/Ref' EndpointSAML: type: object properties: enabled: description: > `true` if the module will be applied to traffic, `false` to disable. default `true` if unspecified type: boolean options_passthrough: description: > Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS. type: boolean cookie_prefix: description: > the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.' type: string inactivity_timeout: description: > 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. type: integer maximum_duration: description: > Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate. type: integer idp_metadata: description: > The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL. type: string force_authn: description: > 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. type: boolean allow_idp_initiated: description: > 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. type: boolean authorized_groups: description: > If present, only users who are a member of one of the listed groups may access the target endpoint. type: array items: type: string entity_id: description: > 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. type: string assertion_consumer_service_url: description: > 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. type: string single_logout_url: description: > 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. type: string request_signing_certificate_pem: description: > 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. type: string metadata_url: description: > 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. type: string nameid_format: description: > 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. type: string EndpointOAuthProvider: type: object properties: github: $ref: '#/components/schemas/EndpointOAuthGitHub' description: | configuration for using github as the identity provider facebook: $ref: '#/components/schemas/EndpointOAuthFacebook' description: | configuration for using facebook as the identity provider microsoft: $ref: '#/components/schemas/EndpointOAuthMicrosoft' description: | configuration for using microsoft as the identity provider google: $ref: '#/components/schemas/EndpointOAuthGoogle' description: | configuration for using google as the identity provider linkedin: $ref: '#/components/schemas/EndpointOAuthLinkedIn' description: | configuration for using linkedin as the identity provider gitlab: $ref: '#/components/schemas/EndpointOAuthGitLab' description: | configuration for using gitlab as the identity provider twitch: $ref: '#/components/schemas/EndpointOAuthTwitch' description: | configuration for using twitch as the identity provider amazon: $ref: '#/components/schemas/EndpointOAuthAmazon' description: | configuration for using amazon as the identity provider Ref: type: object properties: id: description: | a resource identifier type: string uri: description: | a uri for locating a resource type: string EndpointOAuthGitHub: type: object properties: client_id: description: > 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. type: string client_secret: description: > 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`. type: string scopes: description: > 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) type: array items: type: string email_addresses: description: > a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string email_domains: description: > a list of email domains of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string teams: description: > 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` type: array items: type: string organizations: description: > 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' type: array items: type: string EndpointOAuthFacebook: type: object properties: client_id: description: > 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. type: string client_secret: description: > 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`. type: string scopes: description: > 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) type: array items: type: string email_addresses: description: > a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string email_domains: description: > a list of email domains of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string EndpointOAuthMicrosoft: type: object properties: client_id: description: > 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. type: string client_secret: description: > 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`. type: string scopes: description: > 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) type: array items: type: string email_addresses: description: > a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string email_domains: description: > a list of email domains of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string EndpointOAuthGoogle: type: object properties: client_id: description: > 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. type: string client_secret: description: > 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`. type: string scopes: description: > 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) type: array items: type: string email_addresses: description: > a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string email_domains: description: > a list of email domains of users authenticated by identity provider who are allowed access to the endpoint type: array items: type: string EndpointOAuthLinkedIn: type: object properties: client_id: description: n/a type: string client_secret: description: n/a type: string scopes: description: n/a type: array items: type: string email_addresses: description: n/a type: array items: type: string email_domains: description: n/a type: array items: type: string EndpointOAuthGitLab: type: object properties: client_id: description: n/a type: string client_secret: description: n/a type: string scopes: description: n/a type: array items: type: string email_addresses: description: n/a type: array items: type: string email_domains: description: n/a type: array items: type: string EndpointOAuthTwitch: type: object properties: client_id: description: n/a type: string client_secret: description: n/a type: string scopes: description: n/a type: array items: type: string email_addresses: description: n/a type: array items: type: string email_domains: description: n/a type: array items: type: string EndpointOAuthAmazon: type: object properties: client_id: description: n/a type: string client_secret: description: n/a type: string scopes: description: n/a type: array items: type: string email_addresses: description: n/a type: array items: type: string email_domains: description: n/a type: array items: type: string securitySchemes: authentication: type: http scheme: bearer ````