With the ngrok agent CLI, you can use built-in commands to interact with the ngrok API.
For more information about the ngrok API and interfacing with it directly, see see the ngrok api page.
tip
If you want to programmatically control the ngrok agent, the Agent
SDKs are usually a more flexible and powerful choice.
The api command provides access to ngrok's API. You can use the API through
one of the api subcommmands.
All api subcommands require an API key. You can configure it either through
a command flag (--api-key) or add it in ngrok's configuration file (api_key).
You can get get the initial API key at https://dashboard.ngrok.com/api.
Additional keys can be created through 'ngrok api api-key create' subcommand.
Creates a new abuse report which will be reviewed by our system and abuse response team. This API is only available to authorized accounts. Contact abuse@ngrok.com to request access
human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
--metadata
arbitrary user-defined data of this API key. optional, max 4096 bytes
--owner-email
If supplied at credential creation, ownership will be assigned to the specified User. Only admins may specify an owner other than themselves. Both owner_id and owner_email may not be specified.
--owner-id
If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.
A Failover backend defines failover behavior within a list of referenced
backends. Traffic is sent to the first backend in the list. If that backend
is offline or no connection can be established, ngrok attempts to connect to
the next backend in the list until one is successful.
A Weighted Backend balances traffic among the referenced backends. Traffic
is assigned proportionally to each based on its weight. The percentage of
traffic is calculated by dividing a backend's weight by the sum of all
weights.
Certificate Authorities are x509 certificates that are used to sign other
x509 certificates. Attach a Certificate Authority to the Mutual TLS module
to verify that the TLS certificate presented by a client has been signed by
this CA. Certificate Authorities are used only for mTLS validation only and
thus a private key is not included in the resource.
Tunnel Credentials are ngrok agent authtokens. They authorize the ngrok
agent to connect the ngrok service as your account. They are installed with
the ngrok config add-authtoken command or by specifying it in the ngrok.yml
configuration file with the authtoken property.
Create a new tunnel authtoken credential. This authtoken credential can be used to start a new tunnel session. The response to this API call is the only time the generated token is available. If you need it for future use, you must save it securely yourself.
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:.example.com which will allow x.example.com, y.example.com, .example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:=example which will allow x=example, y=example, etc. A rule of '' is equivalent to no acl at all and will explicitly permit all actions.
--description
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
--owner-email
If supplied at credential creation, ownership will be assigned to the specified User. Only admins may specify an owner other than themselves. Both owner_id and owner_email may not be specified.
--owner-id
If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.
--precomputed-token
Only authorized accounts may supply a pre-computed token that will be associated with the created credentials.
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:.example.com which will allow x.example.com, y.example.com, .example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:=example which will allow x=example, y=example, etc. A rule of '' is equivalent to no acl at all and will explicitly permit all actions.
--description
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
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.
--module.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.inactivity-timeout
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.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--module.provider.amazon.client-id
--module.provider.amazon.client-secret
--module.provider.amazon.email-addresses
--module.provider.amazon.email-domains
--module.provider.amazon.scopes
--module.provider.facebook.client-id
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.
--module.provider.facebook.client-secret
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.
--module.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.facebook.scopes
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)
--module.provider.github.client-id
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.
--module.provider.github.client-secret
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.
--module.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.github.organizations
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'
--module.provider.github.scopes
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)
--module.provider.github.teams
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
--module.provider.gitlab.client-id
--module.provider.gitlab.client-secret
--module.provider.gitlab.email-addresses
--module.provider.gitlab.email-domains
--module.provider.gitlab.scopes
--module.provider.google.client-id
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.
--module.provider.google.client-secret
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.
--module.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.google.scopes
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)
--module.provider.linkedin.client-id
--module.provider.linkedin.client-secret
--module.provider.linkedin.email-addresses
--module.provider.linkedin.email-domains
--module.provider.linkedin.scopes
--module.provider.microsoft.client-id
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.
--module.provider.microsoft.client-secret
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.
--module.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.microsoft.scopes
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)
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.inactivity-timeout
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.
--module.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--module.scopes
The set of scopes to request from the OIDC identity provider.
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.
--module.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--module.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.force-authn
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.
--module.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--module.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--module.inactivity-timeout
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.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.nameid-format
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.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--module.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
human-readable description of what this edge will be used for; optional, max 255 bytes.
--hostports
hostports served by this edge
--metadata
arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
Updates an HTTPS Edge by ID. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.
human-readable description of what this edge will be used for; optional, max 255 bytes.
--hostports
hostports served by this edge
--metadata
arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.error-threshold-percentage
Error threshold percentage should be between 0 - 1.0, not 0-100.0
--circuit-breaker.num-buckets
Integer number of buckets into which metrics are retained. Max 128.
--circuit-breaker.rolling-window
Integer number of seconds in the statistical rolling window that metrics are retained for.
--circuit-breaker.tripped-duration
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
--circuit-breaker.volume-threshold
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
--compression.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this edge will be used for; optional, max 255 bytes.
--ip-restriction.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-restriction.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--match
Route selector: "/blog" or "example.com" or "example.com/blog"
--match-type
Type of match to use for this route. Valid values are "exact_path" and "path_prefix".
--metadata
arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
--oauth.auth-check-interval
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.
--oauth.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oauth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.inactivity-timeout
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.
--oauth.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oauth.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oauth.provider.amazon.client-id
--oauth.provider.amazon.client-secret
--oauth.provider.amazon.email-addresses
--oauth.provider.amazon.email-domains
--oauth.provider.amazon.scopes
--oauth.provider.facebook.client-id
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.
--oauth.provider.facebook.client-secret
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.
--oauth.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.scopes
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)
--oauth.provider.github.client-id
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.
--oauth.provider.github.client-secret
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.
--oauth.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.organizations
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'
--oauth.provider.github.scopes
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)
--oauth.provider.github.teams
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
--oauth.provider.gitlab.client-id
--oauth.provider.gitlab.client-secret
--oauth.provider.gitlab.email-addresses
--oauth.provider.gitlab.email-domains
--oauth.provider.gitlab.scopes
--oauth.provider.google.client-id
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.
--oauth.provider.google.client-secret
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.
--oauth.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.scopes
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)
--oauth.provider.linkedin.client-id
--oauth.provider.linkedin.client-secret
--oauth.provider.linkedin.email-addresses
--oauth.provider.linkedin.email-domains
--oauth.provider.linkedin.scopes
--oauth.provider.microsoft.client-id
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.
--oauth.provider.microsoft.client-secret
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.
--oauth.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.scopes
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)
--oauth.provider.twitch.client-id
--oauth.provider.twitch.client-secret
--oauth.provider.twitch.email-addresses
--oauth.provider.twitch.email-domains
--oauth.provider.twitch.scopes
--oidc.client-id
The OIDC app's client ID and OIDC audience.
--oidc.client-secret
The OIDC app's client secret.
--oidc.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oidc.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oidc.inactivity-timeout
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.
--oidc.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--oidc.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oidc.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oidc.scopes
The set of scopes to request from the OIDC identity provider.
--request-headers.add
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
--request-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--request-headers.remove
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
--response-headers.add
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
--response-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--response-headers.remove
a list of header names that will be removed from the HTTP Response returned to the HTTP client
--saml.allow-idp-initiated
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.
--saml.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--saml.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--saml.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--saml.force-authn
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.
--saml.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--saml.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--saml.inactivity-timeout
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.
--saml.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--saml.nameid-format
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.
--saml.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--traffic-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--traffic-policy.value
the traffic policy that should be applied to the traffic on your endpoint.
--user-agent-filter.allow
--user-agent-filter.deny
--user-agent-filter.enabled
--webhook-verification.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
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.
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.error-threshold-percentage
Error threshold percentage should be between 0 - 1.0, not 0-100.0
--circuit-breaker.num-buckets
Integer number of buckets into which metrics are retained. Max 128.
--circuit-breaker.rolling-window
Integer number of seconds in the statistical rolling window that metrics are retained for.
--circuit-breaker.tripped-duration
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
--circuit-breaker.volume-threshold
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
--compression.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this edge will be used for; optional, max 255 bytes.
--ip-restriction.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-restriction.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--match
Route selector: "/blog" or "example.com" or "example.com/blog"
--match-type
Type of match to use for this route. Valid values are "exact_path" and "path_prefix".
--metadata
arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
--oauth.auth-check-interval
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.
--oauth.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oauth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.inactivity-timeout
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.
--oauth.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oauth.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oauth.provider.amazon.client-id
--oauth.provider.amazon.client-secret
--oauth.provider.amazon.email-addresses
--oauth.provider.amazon.email-domains
--oauth.provider.amazon.scopes
--oauth.provider.facebook.client-id
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.
--oauth.provider.facebook.client-secret
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.
--oauth.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.scopes
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)
--oauth.provider.github.client-id
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.
--oauth.provider.github.client-secret
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.
--oauth.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.organizations
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'
--oauth.provider.github.scopes
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)
--oauth.provider.github.teams
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
--oauth.provider.gitlab.client-id
--oauth.provider.gitlab.client-secret
--oauth.provider.gitlab.email-addresses
--oauth.provider.gitlab.email-domains
--oauth.provider.gitlab.scopes
--oauth.provider.google.client-id
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.
--oauth.provider.google.client-secret
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.
--oauth.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.scopes
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)
--oauth.provider.linkedin.client-id
--oauth.provider.linkedin.client-secret
--oauth.provider.linkedin.email-addresses
--oauth.provider.linkedin.email-domains
--oauth.provider.linkedin.scopes
--oauth.provider.microsoft.client-id
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.
--oauth.provider.microsoft.client-secret
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.
--oauth.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.scopes
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)
--oauth.provider.twitch.client-id
--oauth.provider.twitch.client-secret
--oauth.provider.twitch.email-addresses
--oauth.provider.twitch.email-domains
--oauth.provider.twitch.scopes
--oidc.client-id
The OIDC app's client ID and OIDC audience.
--oidc.client-secret
The OIDC app's client secret.
--oidc.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oidc.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oidc.inactivity-timeout
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.
--oidc.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--oidc.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oidc.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oidc.scopes
The set of scopes to request from the OIDC identity provider.
--request-headers.add
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
--request-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--request-headers.remove
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
--response-headers.add
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
--response-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--response-headers.remove
a list of header names that will be removed from the HTTP Response returned to the HTTP client
--saml.allow-idp-initiated
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.
--saml.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--saml.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--saml.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--saml.force-authn
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.
--saml.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--saml.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--saml.inactivity-timeout
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.
--saml.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--saml.nameid-format
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.
--saml.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--traffic-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--traffic-policy.value
the traffic policy that should be applied to the traffic on your endpoint.
--user-agent-filter.allow
--user-agent-filter.deny
--user-agent-filter.enabled
--webhook-verification.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
Updates a TCP Edge by ID. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this edge will be used for; optional, max 255 bytes.
--hostports
hostports served by this edge
--ip-restriction.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-restriction.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--metadata
arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--tls-termination.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
--traffic-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--traffic-policy.value
the traffic policy that should be applied to the traffic on your endpoint.
Updates a TLS Edge by ID. If a module is not specified in the update, it will not be modified. However, each module configuration that is specified will completely replace the existing value. There is no way to delete an existing module via this API, instead use the delete module API.
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this edge will be used for; optional, max 255 bytes.
--hostports
hostports served by this edge
--ip-restriction.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-restriction.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--metadata
arbitrary user-defined machine-readable data of this edge. Optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--tls-termination.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
--traffic-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--traffic-policy.value
the traffic policy that should be applied to the traffic on your endpoint.
Endpoint Configurations are a reusable group of modules that encapsulate how
traffic to a domain or address is handled. Endpoint configurations are only
applied to Domains and TCP Addresses they have been attached to.
true if the module will be applied to traffic, false to disable. default true if unspecified
--basic-auth.allow-options
true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
--basic-auth.auth-provider-id
determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password specified by the ngrok agent's --basic-auth flag, if any.
--basic-auth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--basic-auth.realm
an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is ngrok
--circuit-breaker.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.error-threshold-percentage
Error threshold percentage should be between 0 - 1.0, not 0-100.0
--circuit-breaker.num-buckets
Integer number of buckets into which metrics are retained. Max 128.
--circuit-breaker.rolling-window
Integer number of seconds in the statistical rolling window that metrics are retained for.
--circuit-breaker.tripped-duration
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
--circuit-breaker.volume-threshold
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
--compression.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
--ip-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-policy.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--metadata
arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.auth-check-interval
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.
--oauth.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oauth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.inactivity-timeout
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.
--oauth.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oauth.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oauth.provider.amazon.client-id
--oauth.provider.amazon.client-secret
--oauth.provider.amazon.email-addresses
--oauth.provider.amazon.email-domains
--oauth.provider.amazon.scopes
--oauth.provider.facebook.client-id
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.
--oauth.provider.facebook.client-secret
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.
--oauth.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.scopes
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)
--oauth.provider.github.client-id
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.
--oauth.provider.github.client-secret
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.
--oauth.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.organizations
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'
--oauth.provider.github.scopes
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)
--oauth.provider.github.teams
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
--oauth.provider.gitlab.client-id
--oauth.provider.gitlab.client-secret
--oauth.provider.gitlab.email-addresses
--oauth.provider.gitlab.email-domains
--oauth.provider.gitlab.scopes
--oauth.provider.google.client-id
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.
--oauth.provider.google.client-secret
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.
--oauth.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.scopes
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)
--oauth.provider.linkedin.client-id
--oauth.provider.linkedin.client-secret
--oauth.provider.linkedin.email-addresses
--oauth.provider.linkedin.email-domains
--oauth.provider.linkedin.scopes
--oauth.provider.microsoft.client-id
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.
--oauth.provider.microsoft.client-secret
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.
--oauth.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.scopes
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)
--oauth.provider.twitch.client-id
--oauth.provider.twitch.client-secret
--oauth.provider.twitch.email-addresses
--oauth.provider.twitch.email-domains
--oauth.provider.twitch.scopes
--oidc.client-id
The OIDC app's client ID and OIDC audience.
--oidc.client-secret
The OIDC app's client secret.
--oidc.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oidc.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oidc.inactivity-timeout
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.
--oidc.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--oidc.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oidc.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oidc.scopes
The set of scopes to request from the OIDC identity provider.
--request-headers.add
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
--request-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--request-headers.remove
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
--response-headers.add
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
--response-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--response-headers.remove
a list of header names that will be removed from the HTTP Response returned to the HTTP client
--saml.allow-idp-initiated
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.
--saml.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--saml.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--saml.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--saml.force-authn
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.
--saml.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--saml.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--saml.inactivity-timeout
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.
--saml.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--saml.nameid-format
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.
--saml.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--tls-termination.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
--type
they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp
--webhook-validation.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
Delete an endpoint configuration. This operation will fail if the endpoint configuration is still referenced by any reserved domain or reserved address.
Updates an endpoint configuration. 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.
true if the module will be applied to traffic, false to disable. default true if unspecified
--basic-auth.allow-options
true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
--basic-auth.auth-provider-id
determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password specified by the ngrok agent's --basic-auth flag, if any.
--basic-auth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--basic-auth.realm
an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is ngrok
--circuit-breaker.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--circuit-breaker.error-threshold-percentage
Error threshold percentage should be between 0 - 1.0, not 0-100.0
--circuit-breaker.num-buckets
Integer number of buckets into which metrics are retained. Max 128.
--circuit-breaker.rolling-window
Integer number of seconds in the statistical rolling window that metrics are retained for.
--circuit-breaker.tripped-duration
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
--circuit-breaker.volume-threshold
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
--compression.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--description
human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes
--ip-policy.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--ip-policy.ip-policy-ids
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
--metadata
arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.
--mutual-tls.certificate-authority-ids
list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection
--mutual-tls.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.auth-check-interval
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.
--oauth.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oauth.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oauth.inactivity-timeout
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.
--oauth.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oauth.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oauth.provider.amazon.client-id
--oauth.provider.amazon.client-secret
--oauth.provider.amazon.email-addresses
--oauth.provider.amazon.email-domains
--oauth.provider.amazon.scopes
--oauth.provider.facebook.client-id
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.
--oauth.provider.facebook.client-secret
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.
--oauth.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.facebook.scopes
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)
--oauth.provider.github.client-id
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.
--oauth.provider.github.client-secret
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.
--oauth.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.github.organizations
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'
--oauth.provider.github.scopes
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)
--oauth.provider.github.teams
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
--oauth.provider.gitlab.client-id
--oauth.provider.gitlab.client-secret
--oauth.provider.gitlab.email-addresses
--oauth.provider.gitlab.email-domains
--oauth.provider.gitlab.scopes
--oauth.provider.google.client-id
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.
--oauth.provider.google.client-secret
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.
--oauth.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.google.scopes
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)
--oauth.provider.linkedin.client-id
--oauth.provider.linkedin.client-secret
--oauth.provider.linkedin.email-addresses
--oauth.provider.linkedin.email-domains
--oauth.provider.linkedin.scopes
--oauth.provider.microsoft.client-id
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.
--oauth.provider.microsoft.client-secret
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.
--oauth.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--oauth.provider.microsoft.scopes
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)
--oauth.provider.twitch.client-id
--oauth.provider.twitch.client-secret
--oauth.provider.twitch.email-addresses
--oauth.provider.twitch.email-domains
--oauth.provider.twitch.scopes
--oidc.client-id
The OIDC app's client ID and OIDC audience.
--oidc.client-secret
The OIDC app's client secret.
--oidc.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--oidc.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--oidc.inactivity-timeout
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.
--oidc.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--oidc.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--oidc.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--oidc.scopes
The set of scopes to request from the OIDC identity provider.
--request-headers.add
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
--request-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--request-headers.remove
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
--response-headers.add
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
--response-headers.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--response-headers.remove
a list of header names that will be removed from the HTTP Response returned to the HTTP client
--saml.allow-idp-initiated
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.
--saml.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--saml.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--saml.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--saml.force-authn
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.
--saml.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--saml.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--saml.inactivity-timeout
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.
--saml.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--saml.nameid-format
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.
--saml.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--tls-termination.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--tls-termination.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--tls-termination.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
--webhook-validation.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
Endpoints provides an API for querying the endpoint objects
which define what tunnel or edge is used to serve a hostport.
Only active endpoints associated with a tunnel or backend are returned.
IP Policies are reusable groups of CIDR ranges with an allow or deny
action. They can be attached to endpoints via the Endpoint Configuration IP
Policy module. They can also be used with IP Restrictions to control source
IP ranges that can start tunnel sessions and connect to the API and dashboard.
this field is deprecated. Please leave it empty and use the ip policy rule object's "action" field instead. It is temporarily retained for backwards compatibility reasons.
--description
human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
Delete an IP policy. If the IP policy is referenced by another object for the purposes of traffic restriction it will be treated as if the IP policy remains but has zero rules.
An IP restriction is a restriction placed on the CIDRs that are allowed to
initiate traffic to a specific aspect of your ngrok account. An IP
restriction has a type which defines the ingress it applies to. IP
restrictions can be used to enforce the source IPs that can make API
requests, log in to the dashboard, start ngrok agents, and connect to your
public-facing endpoints.
human-readable description of this IP restriction. optional, max 255 bytes.
--enforced
true if the IP restriction will be enforced. if false, only warnings will be issued
--ip-policy-ids
the set of IP policy identifiers that are used to enforce the restriction
--metadata
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
--type
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
KubernetesOperators is used by the Kubernetes Operator to register and
manage its own resource, as well as for users to see active kubernetes
clusters.
CSR is supplied during initial creation to enable creating a mutual TLS secured connection between ngrok and the operator. This is an internal implementation detail and subject to change.
--binding.endpoint-selectors
the list of cel expressions that filter the bound endpoints for this operator
--binding.ingress-endpoint
the public ingress endpoint for this Kubernetes Operator
--deployment.cluster-name
user-given name for the cluster the Kubernetes Operator is deployed to
--deployment.name
the deployment name
--deployment.namespace
the namespace this Kubernetes Operator is deployed to
--deployment.version
the version of this Kubernetes Operator
--description
human-readable description of this Kubernetes Operator. optional, max 255 bytes.
--enabled-features
features enabled for this Kubernetes Operator. a subset of "bindings", "ingress", and "gateway"
--metadata
arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
--region
the ngrok region in which the ingress for this operator is served. defaults to "global"
CSR is supplied during initial creation to enable creating a mutual TLS secured connection between ngrok and the operator. This is an internal implementation detail and subject to change.
--binding.endpoint-selectors
the list of cel expressions that filter the k8s bound endpoints for this operator
--binding.ingress-endpoint
the public ingress endpoint for this Kubernetes Operator
--deployment.name
the deployment name
--deployment.version
the version of this Kubernetes Operator
--description
human-readable description of this Kubernetes Operator. optional, max 255 bytes.
--enabled-features
features enabled for this Kubernetes Operator. a subset of "bindings", "ingress", and "gateway"
--metadata
arbitrary user-defined machine-readable data of this Kubernetes Operator. optional, max 4096 bytes.
--region
the ngrok region in which the ingress for this operator is served. defaults to "global"
true or false indicating whether to allow OPTIONS requests through without authentication which is necessary for CORS. default is false
--module.auth-provider-id
determines how the basic auth credentials are validated. Currently only the value agent is supported which means that credentials will be validated against the username and password specified by the ngrok agent's --basic-auth flag, if any.
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.realm
an arbitrary string to be specified in as the 'realm' value in the WWW-Authenticate header. default is ngrok
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.
--module.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.inactivity-timeout
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.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--module.provider.amazon.client-id
--module.provider.amazon.client-secret
--module.provider.amazon.email-addresses
--module.provider.amazon.email-domains
--module.provider.amazon.scopes
--module.provider.facebook.client-id
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.
--module.provider.facebook.client-secret
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.
--module.provider.facebook.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.facebook.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.facebook.scopes
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)
--module.provider.github.client-id
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.
--module.provider.github.client-secret
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.
--module.provider.github.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.github.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.github.organizations
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'
--module.provider.github.scopes
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)
--module.provider.github.teams
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
--module.provider.gitlab.client-id
--module.provider.gitlab.client-secret
--module.provider.gitlab.email-addresses
--module.provider.gitlab.email-domains
--module.provider.gitlab.scopes
--module.provider.google.client-id
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.
--module.provider.google.client-secret
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.
--module.provider.google.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.google.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.google.scopes
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)
--module.provider.linkedin.client-id
--module.provider.linkedin.client-secret
--module.provider.linkedin.email-addresses
--module.provider.linkedin.email-domains
--module.provider.linkedin.scopes
--module.provider.microsoft.client-id
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.
--module.provider.microsoft.client-secret
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.
--module.provider.microsoft.email-addresses
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.microsoft.email-domains
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
--module.provider.microsoft.scopes
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)
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.inactivity-timeout
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.
--module.issuer
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
--module.scopes
The set of scopes to request from the OIDC identity provider.
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.
--module.authorized-groups
If present, only users who are a member of one of the listed groups may access the target endpoint.
--module.cookie-prefix
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
--module.enabled
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.force-authn
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.
--module.idp-metadata
The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.
--module.idp-metadata-url
The IdP's metadata URL which returns the XML IdP EntityDescriptor. The IdP's metadata URL specifies how to connect to the IdP as well as its public key which is then used to validate the signature on incoming SAML assertions to the ACS endpoint.
--module.inactivity-timeout
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.
--module.maximum-duration
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
--module.nameid-format
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.
--module.options-passthrough
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
true if the module will be applied to traffic, false to disable. default true if unspecified
--module.min-version
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
--module.terminate-at
edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.
Reserved Addresses are TCP addresses that can be used to listen for traffic.
TCP address hostnames and ports are assigned by ngrok, they cannot be
chosen.
Reserved Domains are hostnames that you can listen for traffic on. Domains
can be used to listen for http, https or tls traffic. You may use a domain
that you own by creating a CNAME record specified in the returned resource.
This CNAME record points traffic for that domain to ngrok's edge servers.
ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with certificate_management_policy.
--certificate-management-policy.authority
certificate authority to request certificates from. The only supported value is letsencrypt.
--certificate-management-policy.private-key-type
type of private key to use when requesting certificates. Defaults to ecdsa, can be either rsa or ecdsa.
--description
human-readable description of what this reserved domain will be used for
--domain
hostname of the reserved domain
--http-endpoint-configuration-id
ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
--https-endpoint-configuration-id
ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
--metadata
arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
--name
the domain name to reserve. It may be a full domain name like app.example.com. If the name does not contain a '.' it will reserve that subdomain on ngrok.io.
--region
deprecated: With the launch of the ngrok Global Network domains traffic is now handled globally. This field applied only to endpoints. Note that agents may still connect to specific regions. Optional, null by default. (au, eu, ap, us, jp, in, sa)
ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with certificate_management_policy.
--certificate-management-policy.authority
certificate authority to request certificates from. The only supported value is letsencrypt.
--certificate-management-policy.private-key-type
type of private key to use when requesting certificates. Defaults to ecdsa, can be either rsa or ecdsa.
--description
human-readable description of what this reserved domain will be used for
--http-endpoint-configuration-id
ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
--https-endpoint-configuration-id
ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
--metadata
arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
--region
deprecated: With the launch of the ngrok Global Network domains traffic is now handled globally. This field applied only to endpoints. Note that agents may still connect to specific regions. Optional, null by default. (au, eu, ap, us, jp, in, sa)
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:.example.com which will allow x.example.com, y.example.com, .example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:=example which will allow x=example, y=example, etc. A rule of '' is equivalent to no acl at all and will explicitly permit all actions.
--description
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
--owner-email
If supplied at credential creation, ownership will be assigned to the specified User. Only admins may specify an owner other than themselves. Both owner_id and owner_email may not be specified.
--owner-id
If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.
--public-key
the PEM-encoded public key of the SSH keypair that will be used to authenticate
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:.example.com which will allow x.example.com, y.example.com, .example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:=example which will allow x=example, y=example, etc. A rule of '' is equivalent to no acl at all and will explicitly permit all actions.
--description
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
SSH Host Certificates along with the corresponding private key allows an SSH
server to assert its authenticity to connecting SSH clients who trust the
SSH Certificate Authority that was used to sign the certificate.
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
--metadata
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
--principals
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
--public-key
a public key in OpenSSH Authorized Keys format that this certificate signs
--ssh-certificate-authority-id
the ssh certificate authority that is used to sign this ssh host certificate
--valid-after
The time when the host certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.
--valid-until
The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of one year in the future will be used. The OpenSSH certificates RFC calls this valid_before.
SSH User Certificates are presented by SSH clients when connecting to an SSH
server to authenticate their connection. The SSH server must trust the SSH
Certificate Authority used to sign the certificate.
human-readable description of this SSH User Certificate. optional, max 255 bytes.
--extensions
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec (https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys) for additional details.
--metadata
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
--principals
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizing the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
--public-key
a public key in OpenSSH Authorized Keys format that this certificate signs
--ssh-certificate-authority-id
the ssh certificate authority that is used to sign this ssh user certificate
--valid-after
The time when the user certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.
--valid-until
The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of 24 hours will be used. The OpenSSH certificates RFC calls this valid_before.
TLS Certificates are pairs of x509 certificates and their matching private
key that can be used to terminate TLS traffic. TLS certificates are unused
until they are attached to a Domain. TLS Certificates may also be
provisioned by ngrok automatically for domains on which you have enabled
automated certificate provisioning.
Tunnel Sessions represent instances of ngrok agents or SSH reverse tunnel
sessions that are running and connected to the ngrok service. Each tunnel
session can include one or more Tunnels.
Issues a command instructing the ngrok agent to restart. The agent restarts itself by calling exec() on platforms that support it. This operation is notably not supported on Windows. When an agent restarts, it reconnects with a new tunnel session ID.
Issues a command instructing the ngrok agent to update itself to the latest version. After this call completes successfully, the ngrok agent will be in the update process. A caller should wait some amount of time to allow the update to complete (at least 10 seconds) before making a call to the Restart endpoint to request that the agent restart itself to start using the new code. This call will never update an ngrok agent to a new major version which could cause breaking compatibility issues. If you wish to update to a new major version, that must be done manually. Still, please be aware that updating your ngrok agent could break your integration. This call will fail in any of the following circumstances: there is no update available the ngrok agent's configuration disabled update checks the agent is currently in process of updating the agent has already successfully updated but has not yet been restarted