ngrok link is a specialized, enhanced version of ngrok specifically designed for running in production environments.
Specifically, it is intended for two major use cases:
It is a lightweight VPN alternative that provides the automation and security necessary to establish targeted, secure links into customer environments.
It enables IoT devices to expose control functionality to customers or administrators at stable, secured endpoints. Remote shell access for debugging and administration can be safely exposed in this manner as well.
ngrok link is tuned for running optimally as part of your infrastructure and exposes a number of additional security
features to give fine grained access and authentication control.
Most importantly, these features are exposed via APIs so that you can automate your entire workflow with ngrok.
Intended Audience
THIS DOCUMENT ASSUMES YOU HAVE ALREADY READ AND UNDERSTOOD the ngrok documentation.
If you have not, you should read the main documentation now. The following content is intended only as a supplement and will not
be helpful without the proper context.
Differences
Because ngrok link is specialized for production environments, there are changes in
the way it operates compared to a 'standard' ngrok agent. Those differences are enumerated here.
The following changes have been made to ngrok's configuration defaults.
Request inspection for all tunnels is disabled by default.
Automatic client updates are disabled by default.
The console UI is disabled and ngrok logs to stdout by default.
Installing ngrok as a service
ngrok link includes additional functionality that makes it easy to install and manage itself
as a native operating system service on Windows, OS X and Linux. This makes it extraordinarily
easy to set up ngrok in a production configuration that will cause it to start on machine boot,
restart after crashes, and integrate with the native tools system administrators are familiar with
to manage and inspect its state.
When running as a service, ngrok configures itself from its configuration file and starts
all tunnels defined in the configuration file. When ngrok runs as a service, it executes the equivalent
behavior of running ngrok start --all.
Installation
Installing ngrok as a service is the same on all on operating systems. First, create
an ngrok.yml configuration file somewhere on your machine. For this example,
I'll assume it's in C:\ngrok\ngrok.yml. In your configuration file, make sure
you include an authtoken and define all of the tunnels that you want to start.
Then run:
ngrok service install -config C:\ngrok\ngrok.yml
This will validate that the configuration file is valid, and if so, install ngrok as a service
using the given configuration file. The service installation includes the location of the ngrok
binary, so don't move or delete it after you've installed the service.
Management
After your service is installed, you probably want to start it. You can easily do that with:
ngrok service start
ngrok exposes the following commands to make service administration easy. The commands
take no arguments and do what you would expect.
ngrok service start
ngrok service stop
ngrok service restart
ngrok service uninstall
Windows
On Windows, ngrok installs itself as a Windows service. It can be managed via Windows Services
and it logs all errors and warnings to the Windows event log.
OS X
On Darwin, ngrok creates an appropriate plist file and installs itself to run via launchd. Warnings
and errors are logged via syslog.
Linux
On Linux, only systems with upstart or systemd installed are supported for service installation. If neither is installed,
you will need to set up your own management of the ngrok process as a service. Warnings and errors are logged via syslog.
Per-client Authtoken Credentials
For production systems, every client must authenticate with a unique authtoken credential. This allows
you to deactivate devices that are old or compromised. Further, it allows you to enforce a separate ACL policy
on every connected device that limits what tunnels it is allowed to bind.
Generation
You can create authtokens from the Tunnel Authtokens tab in your ngrok dashboard. Click "Add Tunnel Authtoken" and then enter a human-readable description of the device or location where you intend to install the authtoken for tracking purposes.
In both the UI and API, the full authtoken you generate will only be shown once, immediately after creation!
ACL Enforcement
Credential ACLs describe what a client who connects with a given authtoken is allowed to do. For example, you may want
to restrict each client to only have permission to bind a specific set of tunnel endpoints. When you create a credential,
specify a list of ACL behaviors are allowed for any client connecting with that authtoken.
Generating credentials with ACLs is only available via the create credential API at the moment.
Endpoint Configurations
Endpoint configurations define reusable pieces of functionality
that can be applied to any number of reserved domains or
reserved addresses on your account.
Endpoint configurations are comprised of one or more modules. Each module defines a piece of functionality
that will be executed on traffic that transits through any domain or address that you attach the endpoint configuration to.
Each module defines its own set of configuration options and may be managed independently via its own API resources.
Modules can perform authentication, performance optimizations like compression, enrich requests, handle errors, enforce policy and more.
Endpoint Configuration Types
Every endpoint configuration must be defined with a type. The type determines both which modules may be added to the
configuration as well as how the configuration may be attached to a reserved domain or reserved address. The documentation
for each module will list the configuration types it may be added to.
There are currently three types of endpoint configurations: http, https, and tcp.
Attaching to Reserved Domains and Addresses
Endpoint configurations may be attached to any number of reserved domains or addresses.
When the configuration is attached, that domain or address will start applying the configuration's modules
to traffic that transits through any tunnels started on those domains or addresses.
Reserved domains have two endpoint configuration references: http_endpoint_configuration_id
and https_endpoint_configuration_id. These govern how http and https traffic are handled, respectively.
The type of configuration that you attach must be http and https, respectively, for
those references.
Reserved addresses have a single endpoint configuration reference endpoint_configuration_id. This configuration
reference must be of type tcp.
Changes to HTTP Traffic
Traffic that is handled by endpoint configurations goes through a new codepath in ngrok's edge servers.
This new codepath has a few subtle changes to how HTTP traffic is handled that are enumerated below:
Header Casing
HTTP headers the backend sees now have their capitalization canonicalized.
The HTTP RFC defines this change as compatible. Previously,
curl --header “foo-BAR: baz” foo.ngrok.io
resulted in the backend seeing
foo-BAR: baz
now it sees:
Foo-Bar: baz
Header Ordering
HTTP headers now may be reordered whereas ngrok previously never re-ordered headers. The HTTP RFC defines this behavior as compatible.
X-Forwarded-For
If an X-Forwarded-For header was supplied by the caller, ngrok now combines those values in a single header field.
The RFC describing X-Forwarded-For describes this as the intended behavior. Previously,
ngrok used to pass through the following hop-by-hop headers. It will now strip them (and set its own values, if necessary).
Keep-Alive
Proxy-Connection
Proxy-Authenticate
Proxy-Authorization
Trailer
Transfer-Encoding
Te
Endpoint Configuration Modules
Circuit Breaker
Supported on types: ,
Circuit breakers are used to protect upstream servers by rejecting traffic to them when they become
overwhelmed, allowing them time to recover back into a steady operational state. When the upstream
server starts to fail requests at too high of a rate, the circuit is "opened".
If the upstream server responds with more than the threshold percentage of requests
with 50X status codes, the circuit breaker pre-emptively reject all subsequent requests at the ngrok edge with a 503
until the upstream server's error rate drops below the threshold percentage.
Compression
Supported on types: ,
The Compression module automatically compresses your responses between the http client and the ngrok edge
which can make your websites load faster on low bandwidth networks.
If an HTTP request includes an Accept-Encoding header, HTTP
responses will be automatically compressed and a Content-Encoding
response header will be added.
If the response was already compressed by the upstream server, ngrok takes no action.
gzip and deflate encodings are supported.
IP Policy
Supported on types: , ,
The IP Policy modules lets you restrict the allowed traffic to tunnel endpoints by explicitly whitelisting
a set of IPs that are permitted to access those endpoints.
Allow connections to the tunnel endpoint only if the source IP of the connection
matches an IP or IP range in any of the specified IP Policies. If multiple policies are specified,
a connection will be allowed if it matches an IP address in any of the policies. Formally, the IP
is checked against a union of all the IP policies.
The IP policy module is intended to replace and deprecate the existing IP Whitelist resource. Please read the documentation section about
IP policy and IP whitelist interactions carefully.
Mutual TLS Authentication
Supported on type:
Also known as "TLS client authentication", connections must complete a mutual TLS handshake
in which the client presents a valid certificate signed by any of the root certificate authorities that you upload.
The Common Name of the client's TLS certificate is injected into the header X-Tls-Client-Cn
that is sent to your application server. This allows you to identify the requesting client for purposes of group membership,
permissioning, revocation checks, profile lookup, etc.
Root CAs must be specified in PEM format. You may specify multiple root CAs by concatenating them together.
OAuth
Supported on type:
The OAuth module enforces an OAuth authentication flow in front of any endpoint it is enabled on. Any HTTP client
accessing an OAuth-protected endpoint will be redirected to a chosen identity provider (currently Google, Microsoft,
Github or Facebook) for authentication. When they are redirected back to the protected endpoint, ngrok will check a
series of authorization constraints that allow you to define who is authorized to access the resource by setting a list
of email addresses, email domains and other requirements. If the user is authorized, their request will be forwarded through
to the upstream server and ngrok's edge will set an HTTP cookie on their browser session to keep them logged in so that
the authentication flow is not repeated.
The Request Headers module allows you to add and remove headers from
HTTP requests before they are sent to your upstream server.
Changes made to request headers will not be visible to other modules;
they will only be seen by your upstream server.
Header addition and removal functions similarly for request and response headers. See HTTP Headers for more details.
Response Headers
Supported on types: ,
The Response Headers module allows you to add and remove headers from
HTTP responses before they are returned to the client. This is
especially useful for enforcing the use of security headers on all
responses returned by your application.
Changes made to response headers will not be visible to other modules;
they will only be seen by the client.
Header addition and removal functions similarly for request and response headers. See HTTP Headers for more details.
TLS Termination
Supported on type:
The TLS Termination module allows you to configure whether ngrok terminates TLS traffic
at its edge or forwards the TLS traffic through unterminated, in which case the TLS
traffic will need to be terminated by your application server (or by the ngrok agent).
If the TLS Termination module is not specified, the default behavior is to terminate all TLS traffic at the ngrok edge.
If the TLS Termination module is enabled and TLS termination has been disabled, then you must have the ngrok agent start
a tls tunnel to receive traffic. Furthermore, if TLS termination is disabled, no other http or https
modules (e.g. Compression, OAuth, etc) will be supported on this endpoint configuration.
If you update a configuration to change whether it terminates TLS traffic or not, all tunnels running with that configuration
will immediately begin to fail requests. All tunnels started with that configuration will need to be stopped and then restarted
with their protocol changed (either https -> tls or vice-versa.
Webhook Validation
Supported on types: ,
The webhook validation module allows ngrok to assert requests to your endoint originate from a supported webhook provider like Slack or Github.
If ngrok can't validate a request as coming from the configured provider it will reject the request with a 403 status.
IP Policies
IP policies are a reusable group of whitelisted IPs or IP ranges (in CIDR blocks) that can be applied on a per-tunnel basis via Endpoint Configurations.
An endpoint configuration may specify one or more IP policies. IP policies may be attached to any number of endpoint configurations. If an endpoint configuration
specifies multiple IP policies, a connection will be allowed if its source IP matches any policy. Formally, the endpoint configuration defines a computed union
of all of its IP policies.
IP Policy Rules
Every IP policy consists of zero or more IP policy rules. Each rule specifies an IP address or IP address range in CIDR notation.
Both IPv4 and IPv6 address notations are supported. An IP policy with no rules is valid and will match no IPs.
Interaction with IP Whitelist
IP policies are intended to replace and deprecate the previous primitive ngrok used for IP enforcement, the IP whitelist. Unlike IP policies which
must be explicitly associated with tunnels via an endpoint configuration, The IP whitelist is an account-wide primitive that applies to all tunnels
on your account.
We do not recommend using both IP policies and the IP whitelist together. But, if you do, a connection will only be allowed through if it matches both
the IP whitelist and the configured IP policies. Formally, for a connection to be accepted, it must match the intersection of both the IP whitelist and
IP policies configured for the matching endpoint configuration.
TLS Certificates
ngrok supports uploading your own TLS certificates which we will use to terminate traffic to a given reserved domain at the ngrok
edge. You may wish to use this functionality in addition to our automatically provisioned certificates if you are using an
EV cert or provisioning certificates from your own certificate authority. Uploading a certificate will not change any traffic, you must
then attach the certificate to a reserved domain by setting the certificate_id property on the reserved domain
with the ID of the certificate you'd like to use for TLS termination.
Certificate Bundles
When uploading a new certificate to ngrok via the API, the certificate_pem field
expects a certificate bundle of all certificates necessary to establish a chain of trust to a trusted root certificate authority.
Many TLS certificate vendors will provide you with a constructed certificate bundle, but some will return the leaf certificate
and the intermediate certificates separately and you must concatenate them to construct the bundle yourself.
Certificate bundles are a series of PEM-encoded X.509 certificates that have been concatenated together in a specific order.
A bundle will look like the following:
The first certificate in the bundle must be the leaf certificate. You can think of the leaf certificate as the
one which is signed for your domain and the private key you will upload.
After the leaf are the intermediates certificates, if any. Each intermediate signs the certificate preceding it in the bundle.
As an example, the first intermediate will have signed the leaf, and that signature is part of the leaf certificate itself.
The final certificate is signed by the root certificate. You may also included the root certificate in the bundle as well,
but it is not necessary or common practice to do so.
Private Keys
ngrok accepts the following formats for the private_key_pem field:
RSA, in either PKCS#1 or PKCS#8 form.
ECDSA, in either SEC 1 or PKCS#8 form.
Ed25519, in PKCS#8 form.
All of the above (PKCS#1, PKCS#8, and SEC 1) are represented with ASN.1 DER (a binary format),
encoded as PEM.
ngrok will not accept any private keys that are encrypted (e.g. with DES)..
OAuth authentication uses configurable constraints to restrict endpoint access to only authorized users.
Upstream servers behind an OAuth-protected endpoint can safely assume that requests are from users
authenticated with the provider and authorized to use the endpoint.
Google
Creating your own application
Step-by-step instructions below follow Google's documentation on setting up OAuth 2.0 for a web application.
Set the Authorization callback URL to https://oauth.ngrok.com/oauth2/callback.
Submit the form. A working example registration:
Save the client ID and client secret from the application overview:
Return to the ngrok dashboard and create or edit an OAuth endpoint configuration module.
Choose to use your own application with GitHub as the provider.
Include the client ID and secret from earlier.
Add any scopes your application requires.
Include the read:user scope (or more permissive, like user) for ngrok.
Add any team or organization constraints by the their mention handle(s), excluding the @ prefix.
For example, the ngrok organization's mention handle is @ngrok, so the organization constraint would be ngrok. Similarly, the @ngrok/developers team would be matched by the constraint ngrok/developers.
If a constraint is specified, the read:org scope is required. A more permissive scope, such as org, also works.
The ngrok managed application can authorize users based on organization or team.
For organizations concerned about membership privacy, your own application should always
be used. When granting third-party access to the managed application,
anyone using the managed application may constrain based on your organization's membership.
Header presence and constraint ordering
Organization and team headers are present only when an organization or team constraint matches.
For example, an endpoint constrained solely on the ngrok organization will always
have authorized users with the ngrok organization header. An endpoint without
any organization or team constraints will receive no organization or team header.
ngrok authorizes against users' first 200 memberships of each constraint in chronological order of
the team or organization's creation. Headers are filled from the first user data match in order:
From any team membership, check the parent organization.
Unique, per-app numeric user ID. From id on the user resource.
ngrok-auth-user-name
User's full name from name on the user resource.
ngrok-auth-email
User's primary email address, from email on the user resource.
ngrok-oauth-access-token
Custom applications only: the user's OAuth access token. It is valid for at least 5 seconds.
User permission revocation
Facebook allows revocation of any permission as part of the authorization flow.
ngrok will enforce that users initially grant all configured permissions. However,
at any time after endpoint authorization, users may selectively revoke permissions. If your application requires more than
the default or email scope, you must follow Facebook's rules
for handling revoked permissions without violating terms of use.
Managed Application Limitations
Managed OAuth applications are owned by ngrok and intended for quick use or testing. We highly recommend that you
bring your own application. There are limitations on managed application since since many endpoints share them:
User access tokens are not provided.
Custom scopes are not allowed.
At least 1 email address or 1 email domain must be specified.
Common email domains are not allowed (e.g. gmail.com, yahoo.com).
Request Modifications
Paths
Upstream servers behind endpoints protected by OAuth should not expect to receive any paths beginning with /oauth2/.
Although more paths may be added, the following paths are currently used by ngrok:
/oauth2/callback
Creates the OAuth session as part of forwarded provider callbacks.
/oauth2/authorize
Initiates capture with a capture URI of /.
This allows easily clearing the session on an error and forcing reauthorization with the provider.
Cookies
ngrok uses cookies to secure the authorization workflow, store user credentials, and cache authorized user
data for headers. Cookie values should be considered opaque and not modified. Cookies names are prefixed
with ngrok. by default. ngrok may overwrite, modify, hide, or delete prefixed cookies
with the names below as part of every request:
session
Stores all user data and credentials.
nonce
Ties an authorization attempt to a single browser. The nonce value is within the cookie name, for example:
ngrok.nonce.1692b0c51436f5ed
Constraint Changes and Sessions
OAuth endpoint configuration uses a cookie-based session. Consider the following when changing authorization
constraints:
Cookies are client-side and available only when users make requests.
Users may successfully authorize, then visit again after any amount of time.
Once authorized, reauthorization occurs after the currently configured authorization check interval or when the endpoint configuration changes.
Sessions are tied to the OAuth client ID and OAuth provider from which they were created.
Sessions are not shared between domain names.
Authorization Check Interval
Authorization check interval controls the frequency of the refresh phase
of the OAuth workflow. In order to prevent abuse, refreshes have minimum frequency of once per 3 minutes.
When configuring an authorization check interval, note that long intervals will result in delayed
authorization against changed provider data. This has security considerations, especially when revoking permissions.
For example, with an authorization check interval of 1 day, the following is possible:
Day 1 08:00: user makes a request and successfully authorizes.
Day 1 10:00: the authorized GitHub organization removes the user.
Day 1 11:00: user successfully accesses the tunnel.
Day 2 08:30: user accesses the tunnel, reauthorizes, and is denied access.
Any of the following actions, taken between step 2 and 3, would force reauthorization:
Updating the authorization check interval to less than two hours.
The default interval is 3 minutes.
Changing the OAuth provider or provider's client ID.
Modifying the endpoint configuration.
Redirecting the user to /oauth2/authorize.
Detailed Auth Workflow
OAuth authentication is best separated into a three phase workflow: capture, callback, and refresh.
Capture
Requests were not previously authorized enter the capture phase and begin OAuth2.
ngrok redirects the user to the provider with a secret state. The state is used to store the
initial request URI, or capture URI, with additional security data. State expires 30 minutes
from capture and will allow users to retry on expiration, discarding the original capture URI in order
to prevent replays.
Methods other than GET also trigger capture; discarding the request body and method in the process.
After successful authentication and authorization, users are redirected with a 302 and perform a GET
against the capture URI.
Callback
Callback occurs as the final user-facing phase. There are up to three redirects made: the provider initiated
redirect to the common callback forwarder, a redirect back to the initial domain, and a final
redirect to the initial capture URI.
As endpoint configurations may be used across many domains, the common callback forwarder serves as a secure proxy back
to the originating domain. Except in cases where the state query parameter was modified or discarded, this redirect is
transparent to the user.
On the originating domain at /oauth2/callback, the request state is verified, errors are handled, and
OAuth is completed. Errors from the provider are displayed to the user with instructions for how to continue. If no errors occur,
a session is written to the session cookie, by default ngrok.session, and users are
redirected to the capture URI.
Refresh
Users that complete provider authorization always complete at least one data refresh. Afterward, this phase is repeated based
on authorization check interval. Refresh populates headers and performs authorization with data from the provider.
If endpoint authorization fails with data from a refresh, granted OAuth credentials from the provider are retained.
Unauthorized users are notified to contact the owner of the application to request access. Subsequent requests repeat
the refresh phase until the maximum session lifetime is reached, the grant expires, or endpoint authorization is updated
to allow them.
HTTP Headers
The Request Headers and Response Headers modules use the same semantics
for header additions and removals.
Headers to add are specified as key/value pairs. Headers to remove are
specified as a list of header names. Header names for both additions
and removals will be canonicalized per the
Changes to HTTP Traffic.
If an added header already exists, the header will appear multiple
times; the original header value will not be overwritten.
If a header is specified for both addition and removal, the original
value will first be removed and the new value used in its place.
Header Templates
Variables can be interpolated into a header value using
JSONPath expressions
surrounded by ${} syntax. For example, using
${.ngrok.request_id} as a header value will cause it to be
filled in with the ngrok-generated Request ID.
At this time, the object used for variable lookup contains the following values:
{
"ngrok": {
// ngrok-generated Request Id
"request_id": "...",
// original client IP
"client_ip": "...",
"geo": {
// two-letter ISO country code based on the client IP
"country_code": "...",
// approximate latitude based on the client IP
"latitude": "...",
// approximate longitude based on the client IP
"longitude": "...",
// the radius in kilometers around the latitude and longitude
// where the client IP is likely to originate from
"lat_long_radius_km": "..."
}
}
}
The ngrok.com REST API
ngrok.com exposes a REST API that grants programmatic access to
all of ngrok's resources.
Base URL and Authentication
Base URL
https://api.ngrok.com/
Authentication
Bearer token authentication with an ngrok.com API key token
The API keys to access the ngrok.com REST API are available on your ngrok.com
dashboard under the Auth tab. API keys can also be created via the API keys API. All requests to the API must include an API key as a bearer token in the Authorization header as demonstrated in the following example.
Request parameters may be encoded to the API using either application/x-www-form-urlencoded or
application/json. Ensure that your client sets the request's Content-Type header appropriately.
All responses returned by the API are application/json.
Versioning and API Stability
The caller must specify a version by sending an Ngrok-Version header with each request.
The latest version is 2. Versions 0 and 1 are supported for some accounts but deprecated.
The ngrok.com API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version.
Examples of non-breaking changes to the API that will not be opt-in include the following.
The addition of new resources
The addition of new methods to existing resources
The addition of new fields on existing resource representations
Bug fixes which change the API to match documented behavior
Pagination
List endpoints can be paginated using the query parameters limit and before_id.
Results are returned ordered from newest to oldest.
The maximum value of limit is 100. If a limit is not specified, it will default to 100.
If before_id is not specified, the first page of results will be returned.
You can provide an explicit value for before_id to retrieve items created before the given ID.
Each response to a list request will include a next_page_uri field, which will be the full URL you can request to retrieve the next page of results.
If there are no more results, next_page_uri will be null.
Create API Key
Create a new API key. The generated API key can be used to authenticateto the ngrok API.
human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata
string
arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at
string
timestamp when the api key was created, RFC 3339 format
token
string
the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata
string
arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at
string
timestamp when the api key was created, RFC 3339 format
token
string
the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
URI of the next page, or null if there is no next page
APIKey fields
id
string
unique API key resource identifier
uri
string
URI to the API resource of this API key
description
string
human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata
string
arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at
string
timestamp when the api key was created, RFC 3339 format
token
string
the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
human-readable description of what uses the API key to authenticate. optional, max 255 bytes.
metadata
string
arbitrary user-defined data of this API key. optional, max 4096 bytes
created_at
string
timestamp when the api key was created, RFC 3339 format
token
string
the bearer token that can be placed into the Authorization header to authenticate request to the ngrok API. This value is only available one time, on the API response from key creation. Otherwise it is null.
Create Abuse Report
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
true if the module will be applied to traffic, false to disable. default true if unspecified
tripped_duration
uint32
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_window
uint32
Integer number of seconds in the statistical rolling window that metrics are retained for.
num_buckets
uint32
Integer number of buckets into which metrics are retained. Max 128.
volume_threshold
uint32
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentage
float64
Error threshold percentage should be between 0 - 1.0, not 0-100.0
EndpointCompression parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
EndpointRequestHeaders parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
add
Map<string, string>
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
remove
List<string>
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
EndpointResponseHeaders parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
add
Map<string, string>
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
remove
List<string>
a list of header names that will be removed from the HTTP Response returned to the HTTP client
EndpointIPPolicyMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
ip_policy_ids
List<string>
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
EndpointMutualTLSMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authority_ids
List<string>
list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection
EndpointTLSTermination parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLoggingMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
event_stream_ids
List<string>
list of all EventStreams that will be used to configure and export this endpoint's logs
EndpointSAMLMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
EndpointOIDC parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointTLSTermination fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLogging fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
list of all EventStreams that will be used to configure and export this endpoint's logs
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointSAML fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
EndpointOIDC fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
Delete Endpoint Configuration
Delete an endpoint configuration. This operation will fail if the endpoint configuration is still referenced by any reserved domain or reserved address.
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointTLSTermination fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLogging fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
list of all EventStreams that will be used to configure and export this endpoint's logs
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointSAML fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
EndpointOIDC fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
List Endpoint Configurations
Returns a list of all endpoint configurations on this account
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointTLSTermination fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLogging fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
list of all EventStreams that will be used to configure and export this endpoint's logs
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointSAML fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
EndpointOIDC fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
Update Endpoint Configuration
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
tripped_duration
uint32
Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health
rolling_window
uint32
Integer number of seconds in the statistical rolling window that metrics are retained for.
num_buckets
uint32
Integer number of buckets into which metrics are retained. Max 128.
volume_threshold
uint32
Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.
error_threshold_percentage
float64
Error threshold percentage should be between 0 - 1.0, not 0-100.0
EndpointCompression parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
EndpointRequestHeaders parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
add
Map<string, string>
a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server
remove
List<string>
a list of header names that will be removed from the HTTP Request before being sent to the upstream application server
EndpointResponseHeaders parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
add
Map<string, string>
a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client
remove
List<string>
a list of header names that will be removed from the HTTP Response returned to the HTTP client
EndpointIPPolicyMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
ip_policy_ids
List<string>
list of all IP policies that will be used to check if a source IP is allowed access to the endpoint
EndpointMutualTLSMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
certificate_authority_ids
List<string>
list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection
EndpointTLSTermination parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLoggingMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
event_stream_ids
List<string>
list of all EventStreams that will be used to configure and export this endpoint's logs
EndpointSAMLMutate parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
EndpointOIDC parameters
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointTLSTermination fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
EndpointWebhookValidation fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
EndpointOAuth fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointLogging fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
list of all EventStreams that will be used to configure and export this endpoint's logs
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
EndpointSAML fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
EndpointOIDC fields
enabled
boolean
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
Create Event Destination
Create a new Event Destination. It will not apply to anything until it is associated with an Event Stream, and that Event Stream is associated with an Endpoint Config.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.
AWSRole fields
role_arn
string
An ARN that specifies the role that ngrok should use to deliver to the configured target.
AWSCredentials fields
aws_access_key_id
string
The ID portion of an AWS access key.
aws_secret_access_key
string
The secret portion of an AWS access key.
Delete Event Destination
Delete an Event Destination. If the Event Destination is still referenced by an Event Stream, this will throw an error until that Event Stream has removed that reference.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
An object that encapsulates where and how to send your events. An event destination must contain exactly one of the following objects, leaving the rest null: kinesis, firehose, cloudwatch_logs, or s3.
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
event_type
string
The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
Timestamp when the Event Stream was created, RFC 3339 format.
metadata
string
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
event_type
string
The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
Delete Event Stream
Delete an Event Stream. Associated Event Destinations will be preserved.
Timestamp when the Event Stream was created, RFC 3339 format.
metadata
string
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
event_type
string
The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
URI of the next page, or null if there is no next page.
EventStream fields
id
string
Unique identifier for this Event Stream.
uri
string
URI of the Event Stream API resource.
created_at
string
Timestamp when the Event Stream was created, RFC 3339 format.
metadata
string
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
event_type
string
The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
Timestamp when the Event Stream was created, RFC 3339 format.
metadata
string
Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.
description
string
Human-readable description of the Event Stream. Optional, max 255 bytes.
fields
List<string>
A list of protocol-specific fields you want to collect on each event.
event_type
string
The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.
destination_ids
List<string>
A list of Event Destination IDs which should be used for this Event Stream. Event Streams are required to have at least one Event Destination.
sampling_rate
float64
The percentage of all events you would like to capture. Valid values range from 0.01, representing 1% of all events to 1.00, representing 100% of all events.
Create IP Policy
Create a new IP policy. It will not apply to any traffic until you associate to a traffic source via an endpoint configuration or IP restriction.
timestamp when the IP policy was created, RFC 3339 format
description
string
human-readable description of the source IPs of this IP policy. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.
action
string
the IP policy action. Supported values are allow or deny
Delete IP Policy
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.
human-readable description of this IP restriction. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced
boolean
true if the IP restriction will be enforce. if false, only warnings will be issued
type
string
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
timestamp when the IP restriction was created, RFC 3339 format
description
string
human-readable description of this IP restriction. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced
boolean
true if the IP restriction will be enforce. if false, only warnings will be issued
type
string
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
timestamp when the IP restriction was created, RFC 3339 format
description
string
human-readable description of this IP restriction. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced
boolean
true if the IP restriction will be enforce. if false, only warnings will be issued
type
string
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
URI of the next page, or null if there is no next page
IPRestriction fields
id
string
unique identifier for this IP restriction
uri
string
URI of the IP restriction API resource
created_at
string
timestamp when the IP restriction was created, RFC 3339 format
description
string
human-readable description of this IP restriction. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced
boolean
true if the IP restriction will be enforce. if false, only warnings will be issued
type
string
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
timestamp when the IP restriction was created, RFC 3339 format
description
string
human-readable description of this IP restriction. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.
enforced
boolean
true if the IP restriction will be enforce. if false, only warnings will be issued
type
string
the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints
human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net
string
an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
timestamp when the IP whitelist entry was created, RFC 3339 format
description
string
human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net
string
an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
timestamp when the IP whitelist entry was created, RFC 3339 format
description
string
human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net
string
an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
the list of all IP whitelist entries on this account
uri
string
URI of the IP whitelist API resource
next_page_uri
string
URI of the next page, or null if there is no next page
IPWhitelistEntry fields
id
string
unique identifier for this IP whitelist entry
uri
string
URI of the IP whitelist entry API resource
created_at
string
timestamp when the IP whitelist entry was created, RFC 3339 format
description
string
human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net
string
an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
timestamp when the IP whitelist entry was created, RFC 3339 format
description
string
human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.
ip_net
string
an IP address or IP network range in CIDR notation (e.g. 10.1.1.1 or 10.1.0.0/16) of addresses that will be whitelisted to communicate with your tunnel endpoints
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle parameters
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval
uint32
Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.
configuration for using google as the identity provider
EndpointOAuthGitHub fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams
List<string>
a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations
List<string>
a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'
EndpointOAuthFacebook fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthMicrosoft fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
EndpointOAuthGoogle fields
client_id
string
the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret
string
the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes
List<string>
a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses
List<string>
a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains
List<string>
a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
issuer
string
URL of the OIDC "OpenID provider". This is the base URL used for discovery.
client_id
string
The OIDC app's client ID and OIDC audience.
client_secret
string
The OIDC app's client secret.
scopes
List<string>
The set of scopes to request from the OIDC identity provider.
the domain name to reserve. It may be a full domain name like app.example.com. If the name does not contain a '.' it will reserve that subdomain on ngrok.io.
region
string
reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
description
string
human-readable description of what this reserved domain will be used for
metadata
string
arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
http_endpoint_configuration_id
string
ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
https_endpoint_configuration_id
string
ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
certificate_id
string
ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.
ReservedDomainCertPolicy parameters
authority
string
certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type
string
type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.
object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed
ReservedDomainCertJob fields
error_code
string
if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg
string
a message describing the current status or error
started_at
string
timestamp when the provisioning job started, RFC 3339 format
retries_at
string
timestamp when the provisioning job will be retried
object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed
ReservedDomainCertJob fields
error_code
string
if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg
string
a message describing the current status or error
started_at
string
timestamp when the provisioning job started, RFC 3339 format
retries_at
string
timestamp when the provisioning job will be retried
object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed
ReservedDomainCertJob fields
error_code
string
if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg
string
a message describing the current status or error
started_at
string
timestamp when the provisioning job started, RFC 3339 format
retries_at
string
timestamp when the provisioning job will be retried
human-readable description of what this reserved domain will be used for
metadata
string
arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
http_endpoint_configuration_id
string
ID of an endpoint configuration of type http that will be used to handle inbound http traffic to this domain
https_endpoint_configuration_id
string
ID of an endpoint configuration of type https that will be used to handle inbound https traffic to this domain
certificate_id
string
ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.
ReservedDomainCertPolicy parameters
authority
string
certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type
string
type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.
object referencing the TLS certificate used for connections to this domain. This can be either a user-uploaded certificate, the most recently issued automatic one, or null otherwise.
status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed
ReservedDomainCertJob fields
error_code
string
if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg
string
a message describing the current status or error
started_at
string
timestamp when the provisioning job started, RFC 3339 format
retries_at
string
timestamp when the provisioning job will be retried
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
true if the module will be applied to traffic, false to disable. default true if unspecified
options_passthrough
boolean
Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix
string
the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout
uint32
Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration
uint32
Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
idp_metadata_url
string
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.
idp_metadata
string
The full XML IdP EntityDescriptor in bytes. This parameter is mutually exclusive with idp_metadata_url. It is recommended to use that parameter instead if the IdP exposes a metadata URL.
force_authn
boolean
If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.
allow_idp_initiated
boolean
If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.
authorized_groups
List<string>
If present, only users who are a member of one of the listed groups may access the target endpoint.
entity_id
string
The SP Entity's unique ID. This always takes the form of a URL. In ngrok's implementation, this URL is the same as the metadata URL. This will need to be specified to the IdP as configuration.
assertion_consumer_service_url
string
The public URL of the SP's Assertion Consumer Service. This is where the IdP will redirect to during an authentication flow. This will need to be specified to the IdP as configuration.
single_logout_url
string
The public URL of the SP's Single Logout Service. This is where the IdP will redirect to during a single logout flow. This will optionally need to be specified to the IdP as configuration.
request_signing_certificate_pem
string
PEM-encoded x.509 certificate of the key pair that is used to sign all SAML requests that the ngrok SP makes to the IdP. Many IdPs do not support request signing verification, but we highly recommend specifying this in the IdP's configuration if it is supported.
metadata_url
string
A public URL where the SP's metadata is hosted. If an IdP supports dynamic configuration, this is the URL it can use to retrieve the SP metadata.
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
public_key
string
the PEM-encoded public key of the SSH keypair that will be used to authenticate
timestamp when the ssh credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key
string
the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
timestamp when the ssh credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key
string
the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
URI of the next page, or null if there is no next page
SSHCredential fields
id
string
unique ssh credential resource identifier
uri
string
URI of the ssh credential API resource
created_at
string
timestamp when the ssh credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key
string
the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
timestamp when the ssh credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.
public_key
string
the PEM-encoded public key of the SSH keypair that will be used to authenticate
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
the ssh certificate authority that is used to sign this ssh host certificate
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
principals
List<string>
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_after
string
The time when the host certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.
valid_until
string
The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of one year in the future will be used. The OpenSSH certificates RFC calls this valid_before.
description
string
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
timestamp when the SSH Host Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh host certificate
principals
List<string>
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
timestamp when the SSH Host Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh host certificate
principals
List<string>
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
List SSH Host Certificates
List all SSH Host Certificates issued on this account
the list of all ssh host certificates on this account
uri
string
URI of the ssh host certificates list API resource
next_page_uri
string
URI of the next page, or null if there is no next page
SSHHostCertificate fields
id
string
unique identifier for this SSH Host Certificate
uri
string
URI of the SSH Host Certificate API resource
created_at
string
timestamp when the SSH Host Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh host certificate
principals
List<string>
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
timestamp when the SSH Host Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH Host Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh host certificate
principals
List<string>
the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
the ssh certificate authority that is used to sign this ssh user certificate
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
principals
List<string>
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_options
Map<string, string>
A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensions
Map<string, string>
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_after
string
The time when the user certificate becomes valid, in RFC 3339 format. Defaults to the current time if unspecified.
valid_until
string
The time when this host certificate becomes invalid, in RFC 3339 format. If unspecified, a default value of 24 hours will be used. The OpenSSH certificates RFC calls this valid_before.
description
string
human-readable description of this SSH User Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
timestamp when the SSH User Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH User Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh user certificate
principals
List<string>
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_options
Map<string, string>
A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensions
Map<string, string>
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
timestamp when the SSH User Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH User Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh user certificate
principals
List<string>
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_options
Map<string, string>
A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensions
Map<string, string>
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
List SSH User Certificates
List all SSH User Certificates issued on this account
the list of all ssh user certificates on this account
uri
string
URI of the ssh user certificates list API resource
next_page_uri
string
URI of the next page, or null if there is no next page
SSHUserCertificate fields
id
string
unique identifier for this SSH User Certificate
uri
string
URI of the SSH User Certificate API resource
created_at
string
timestamp when the SSH User Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH User Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh user certificate
principals
List<string>
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_options
Map<string, string>
A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensions
Map<string, string>
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
timestamp when the SSH User Certificate API resource was created, RFC 3339 format
description
string
human-readable description of this SSH User Certificate. optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.
public_key
string
a public key in OpenSSH Authorized Keys format that this certificate signs
key_type
string
the key type of the public_key, one of rsa, ecdsa or ed25519
ssh_certificate_authority_id
string
the ssh certificate authority that is used to sign this ssh user certificate
principals
List<string>
the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.
critical_options
Map<string, string>
A map of critical options included in the certificate. Only two critical options are currently defined by OpenSSH: force-command and source-address. See the OpenSSH certificate protocol spec for additional details.
extensions
Map<string, string>
A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec for additional details.
valid_after
string
the time when the ssh host certificate becomes valid, in RFC 3339 format.
valid_until
string
the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.
certificate
string
the signed SSH certificate in OpenSSH Authorized Keys Format. this value should be placed in a -cert.pub certificate file on disk that should be referenced in your sshd_config configuration file with a HostCertificate directive
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
true if the module will be applied to traffic, false to disable. default true if unspecified
terminate_at
string
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.
min_version
string
The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.
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.
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
timestamp when the tunnel credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
token
string
the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation, otherwise it is null.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
timestamp when the tunnel credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
token
string
the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation, otherwise it is null.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
List Tunnel Credentials
List all tunnel authtoken credentials on this account
the list of all tunnel credentials on this account
uri
string
URI of the tunnel credential list API resource
next_page_uri
string
URI of the next page, or null if there is no next page
Credential fields
id
string
unique tunnel credential resource identifier
uri
string
URI of the tunnel credential API resource
created_at
string
timestamp when the tunnel credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
token
string
the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation, otherwise it is null.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
Update Tunnel Credential
Update attributes of an tunnel authtoken credential by ID
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
timestamp when the tunnel credential was created, RFC 3339 format
description
string
human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.
metadata
string
arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.
token
string
the credential's authtoken that can be used to authenticate an ngrok client. This value is only available one time, on the API response from credential creation, otherwise it is null.
acl
List<string>
optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains and addresses 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 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. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.
List Tunnel Sessions
List all online tunnel sessions running on this account.
reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session
id
string
unique tunnel session resource identifier
ip
string
source ip address of the tunnel session
metadata
string
arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option
os
string
operating system of the host the ngrok agent is running on
region
string
the ngrok region identifier in which this tunnel session was started
started_at
string
time when the tunnel session first connected to the ngrok servers
transport
string
the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh
uri
string
URI to the API resource of the tunnel session
Ref fields
id
string
a resource identifier
uri
string
a uri for locating a resource
Restart Tunnel Agent
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
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret
true if the module will be applied to traffic, false to disable. default true if unspecified
provider
string
a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers: SLACK, SNS, STRIPE, GITHUB, TWILIO, SHOPIFY, GITLAB, INTERCOM.
secret
string
a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret