Datatypes

This module contains all datatypes returned by the ngrok API.

class ngrok.datatypes.APIKey(client, props)[source]
property created_at

timestamp when the api key was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of what uses the API key to authenticate. optional, max 255 bytes.

Return type

str

property id

unique API key resource identifier

Return type

str

property metadata

arbitrary user-defined data of this API key. optional, max 4096 bytes

Return type

str

property token

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.

Return type

str

update(description=None, metadata=None)[source]
property uri

URI to the API resource of this API key

Return type

str

class ngrok.datatypes.APIKeyList(client, props)[source]
property keys

the list of API keys for this account

Return type

Sequence[APIKey]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the API keys list API resource

Return type

str

class ngrok.datatypes.AWSAuth(client, props)[source]
property creds

Credentials to your AWS account if you prefer ngrok to sign in with long-term access keys.

Return type

AWSCredentials

property role

A role for ngrok to assume on your behalf to deposit events into your AWS account.

Return type

AWSRole

class ngrok.datatypes.AWSCredentials(client, props)[source]
property aws_access_key_id

The ID portion of an AWS access key.

Return type

str

property aws_secret_access_key

The secret portion of an AWS access key.

Return type

str

class ngrok.datatypes.AWSRole(client, props)[source]
property role_arn

An ARN that specifies the role that ngrok should use to deliver to the configured target.

Return type

str

class ngrok.datatypes.AbuseReport(client, props)[source]
property created_at

timestamp that the abuse report record was created in RFC 3339 format

Return type

str

property hostnames

an array of hostname statuses related to the report

Return type

Sequence[AbuseReportHostname]

property id

ID of the abuse report

Return type

str

property metadata

arbitrary user-defined data about this abuse report. Optional, max 4096 bytes.

Return type

str

property status

Indicates whether ngrok has processed the abuse report. one of PENDING, PROCESSED, or PARTIALLY_PROCESSED

Return type

str

property uri

URI of the abuse report API resource

Return type

str

property urls

a list of URLs containing suspected abusive content

Return type

Sequence[str]

class ngrok.datatypes.AbuseReportHostname(client, props)[source]
property hostname

the hostname ngrok has parsed out of one of the reported URLs in this abuse report

Return type

str

property status

indicates what action ngrok has taken against the hostname. one of PENDING, BANNED, UNBANNED, or IGNORE

Return type

str

class ngrok.datatypes.CertificateAuthority(client, props)[source]
property ca_pem

raw PEM of the Certificate Authority

Return type

str

property created_at

timestamp when the Certificate Authority was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of this Certificate Authority. optional, max 255 bytes.

Return type

str

property extended_key_usages

extended set of actions the private key of this Certificate Authority can be used for

Return type

Sequence[str]

property id

unique identifier for this Certificate Authority

Return type

str

property key_usages

set of actions the private key of this Certificate Authority can be used for

Return type

Sequence[str]

property metadata

arbitrary user-defined machine-readable data of this Certificate Authority. optional, max 4096 bytes.

Return type

str

property not_after

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

Return type

str

property not_before

timestamp when this Certificate Authority becomes valid, RFC 3339 format

Return type

str

property subject_common_name

subject common name of the Certificate Authority

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the Certificate Authority API resource

Return type

str

class ngrok.datatypes.CertificateAuthorityList(client, props)[source]
property certificate_authorities

the list of all certificate authorities on this account

Return type

Sequence[CertificateAuthority]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the certificates authorities list API resource

Return type

str

class ngrok.datatypes.Credential(client, props)[source]
property acl

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.

Return type

Sequence[str]

property created_at

timestamp when the tunnel credential was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of who or what will use the credential to authenticate. Optional, max 255 bytes.

Return type

str

property id

unique tunnel credential resource identifier

Return type

str

property metadata

arbitrary user-defined machine-readable data of this credential. Optional, max 4096 bytes.

Return type

str

property token

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.

Return type

str

update(description=None, metadata=None, acl=None)[source]
property uri

URI of the tunnel credential API resource

Return type

str

class ngrok.datatypes.CredentialList(client, props)[source]
property credentials

the list of all tunnel credentials on this account

Return type

Sequence[Credential]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the tunnel credential list API resource

Return type

str

class ngrok.datatypes.EndpointCircuitBreaker(client, props)[source]
property enabled

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

Return type

bool

property error_threshold_percentage

Error threshold percentage should be between 0 - 1.0, not 0-100.0

Return type

float

property num_buckets

Integer number of buckets into which metrics are retained. Max 128.

Return type

int

property rolling_window

Integer number of seconds in the statistical rolling window that metrics are retained for.

Return type

int

property tripped_duration

Integer number of seconds after which the circuit is tripped to wait before re-evaluating upstream health

Return type

int

property volume_threshold

Integer number of requests in a rolling window that will trip the circuit. Helpful if traffic volume is low.

Return type

int

class ngrok.datatypes.EndpointCompression(client, props)[source]
property enabled

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

Return type

bool

class ngrok.datatypes.EndpointConfiguration(client, props)[source]
property circuit_breaker

circuit breaker module configuration or null

Return type

EndpointCircuitBreaker

property compression

compression module configuration or null

Return type

EndpointCompression

property created_at

timestamp when the endpoint configuration was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of what this endpoint configuration will be do when applied or what traffic it will be applied to. Optional, max 255 bytes

Return type

str

property id

unique identifier of this endpoint configuration

Return type

str

property ip_policy

ip policy module configuration or null

Return type

EndpointIPPolicy

property logging

logging module configuration or null

Return type

EndpointLogging

property metadata

arbitrary user-defined machine-readable data of this endpoint configuration. Optional, max 4096 bytes.

Return type

str

property mutual_tls

mutual TLS module configuration or null

Return type

EndpointMutualTLS

property oauth

oauth module configuration or null

Return type

EndpointOAuth

property oidc

oidc module configuration or null

Return type

EndpointOIDC

property request_headers

request headers module configuration or null

Return type

EndpointRequestHeaders

property response_headers

response headers module configuration or null

Return type

EndpointResponseHeaders

property saml

saml module configuration or null

Return type

EndpointSAML

property tls_termination

TLS termination module configuration or null

Return type

EndpointTLSTermination

property type

they type of traffic this endpoint configuration can be applied to. one of: http, https, tcp

Return type

str

update(description=None, metadata=None, circuit_breaker=None, compression=None, request_headers=None, response_headers=None, ip_policy=None, mutual_tls=None, tls_termination=None, webhook_validation=None, oauth=None, logging=None, saml=None, oidc=None)[source]
property uri

URI of the endpoint configuration API resource

Return type

str

property webhook_validation

webhook validation module configuration or null

Return type

EndpointWebhookValidation

class ngrok.datatypes.EndpointConfigurationList(client, props)[source]
property endpoint_configurations

the list of all endpoint configurations on this account

Return type

Sequence[EndpointConfiguration]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the endpoint configurations list API resource

Return type

str

class ngrok.datatypes.EndpointIPPolicy(client, props)[source]
property enabled

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

Return type

bool

property ip_policies
Return type

Sequence[Ref]

class ngrok.datatypes.EndpointIPPolicyMutate(client, props)[source]
property enabled

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

Return type

bool

property ip_policy_ids

list of all IP policies that will be used to check if a source IP is allowed access to the endpoint

Return type

Sequence[str]

class ngrok.datatypes.EndpointLogging(client, props)[source]
property enabled

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

Return type

bool

property event_streams

list of all EventStreams that will be used to configure and export this endpoint’s logs

Return type

Sequence[Ref]

class ngrok.datatypes.EndpointLoggingMutate(client, props)[source]
property enabled

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

Return type

bool

property event_stream_ids

list of all EventStreams that will be used to configure and export this endpoint’s logs

Return type

Sequence[str]

class ngrok.datatypes.EndpointMutualTLS(client, props)[source]
property certificate_authorities

PEM-encoded CA certificates that will be used to validate. Multiple CAs may be provided by concatenating them together.

Return type

Sequence[Ref]

property enabled

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

Return type

bool

class ngrok.datatypes.EndpointMutualTLSMutate(client, props)[source]
property certificate_authority_ids

list of certificate authorities that will be used to validate the TLS client certificate presnted by the initiatiator of the TLS connection

Return type

Sequence[str]

property enabled

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

Return type

bool

class ngrok.datatypes.EndpointOAuth(client, props)[source]
property auth_check_interval

Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

Return type

int

property cookie_prefix

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

Return type

str

property enabled

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

Return type

bool

property inactivity_timeout

Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.

Return type

int

property maximum_duration

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

Return type

int

property options_passthrough

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

Return type

bool

property provider

an object which defines the identity provider to use for authentication and configuration for who may access the endpoint

Return type

EndpointOAuthProvider

class ngrok.datatypes.EndpointOAuthFacebook(client, props)[source]
property client_id

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

Return type

str

property client_secret

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

Return type

str

property email_addresses

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property email_domains

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property scopes

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

Return type

Sequence[str]

class ngrok.datatypes.EndpointOAuthGitHub(client, props)[source]
property client_id

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

Return type

str

property client_secret

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

Return type

str

property email_addresses

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property email_domains

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property organizations

a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization’s ‘slug’

Return type

Sequence[str]

property scopes

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

Return type

Sequence[str]

property teams

a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the ‘slug’ format qualified with the org name, e.g. org-name/team-name

Return type

Sequence[str]

class ngrok.datatypes.EndpointOAuthGoogle(client, props)[source]
property client_id

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

Return type

str

property client_secret

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

Return type

str

property email_addresses

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property email_domains

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property scopes

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

Return type

Sequence[str]

class ngrok.datatypes.EndpointOAuthMicrosoft(client, props)[source]
property client_id

the OAuth app client ID. retrieve it from the identity provider’s dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.

Return type

str

property client_secret

the OAuth app client secret. retrieve if from the identity provider’s dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.

Return type

str

property email_addresses

a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property email_domains

a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

Return type

Sequence[str]

property scopes

a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)

Return type

Sequence[str]

class ngrok.datatypes.EndpointOAuthProvider(client, props)[source]
property facebook

configuration for using facebook as the identity provider

Return type

EndpointOAuthFacebook

property github

configuration for using github as the identity provider

Return type

EndpointOAuthGitHub

property google

configuration for using google as the identity provider

Return type

EndpointOAuthGoogle

property microsoft

configuration for using microsoft as the identity provider

Return type

EndpointOAuthMicrosoft

class ngrok.datatypes.EndpointOIDC(client, props)[source]
property client_id

The OIDC app’s client ID and OIDC audience.

Return type

str

property client_secret

The OIDC app’s client secret.

Return type

str

property cookie_prefix

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

Return type

str

property enabled

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

Return type

bool

property inactivity_timeout

Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.

Return type

int

property issuer

URL of the OIDC “OpenID provider”. This is the base URL used for discovery.

Return type

str

property maximum_duration

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

Return type

int

property options_passthrough

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

Return type

bool

property scopes

The set of scopes to request from the OIDC identity provider.

Return type

Sequence[str]

class ngrok.datatypes.EndpointRequestHeaders(client, props)[source]
property add

a map of header key to header value that will be injected into the HTTP Request before being sent to the upstream application server

Return type

Mapping[str, str]

property enabled

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

Return type

bool

property remove

a list of header names that will be removed from the HTTP Request before being sent to the upstream application server

Return type

Sequence[str]

class ngrok.datatypes.EndpointResponseHeaders(client, props)[source]
property add

a map of header key to header value that will be injected into the HTTP Response returned to the HTTP client

Return type

Mapping[str, str]

property enabled

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

Return type

bool

property remove

a list of header names that will be removed from the HTTP Response returned to the HTTP client

Return type

Sequence[str]

class ngrok.datatypes.EndpointSAML(client, props)[source]
property allow_idp_initiated

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

Return type

bool

property assertion_consumer_service_url

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.

Return type

str

property authorized_groups

If present, only users who are a member of one of the listed groups may access the target endpoint.

Return type

Sequence[str]

property cookie_prefix

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

Return type

str

property enabled

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

Return type

bool

property entity_id

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.

Return type

str

property force_authn

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

Return type

bool

property idp_metadata

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

Return type

str

property inactivity_timeout

Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.

Return type

int

property maximum_duration

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

Return type

int

property metadata_url

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.

Return type

str

property nameid_format

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Return type

str

property options_passthrough

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

Return type

bool

property request_signing_certificate_pem

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.

Return type

str

property single_logout_url

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.

Return type

str

class ngrok.datatypes.EndpointSAMLMutate(client, props)[source]
property allow_idp_initiated

If true, the IdP may initiate a login directly (e.g. the user does not need to visit the endpoint first and then be redirected). The IdP should set the RelayState parameter to the target URL of the resource they want the user to be redirected to after the SAML login assertion has been processed.

Return type

bool

property authorized_groups

If present, only users who are a member of one of the listed groups may access the target endpoint.

Return type

Sequence[str]

property cookie_prefix

the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is ‘ngrok.’

Return type

str

property enabled

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

Return type

bool

property force_authn

If true, indicates that whenever we redirect a user to the IdP for authentication that the IdP must prompt the user for authentication credentials even if the user already has a valid session with the IdP.

Return type

bool

property idp_metadata

The full XML IdP EntityDescriptor. Your IdP may provide this to you as a a file to download or as a URL.

Return type

str

property inactivity_timeout

Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.

Return type

int

property maximum_duration

Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.

Return type

int

property nameid_format

Defines the name identifier format the SP expects the IdP to use in its assertions to identify subjects. If unspecified, a default value of urn:oasis:names:tc:SAML:2.0:nameid-format:persistent will be used. A subset of the allowed values enumerated by the SAML specification are supported.

Return type

str

property options_passthrough

Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.

Return type

bool

class ngrok.datatypes.EndpointTLSTermination(client, props)[source]
property enabled

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

Return type

bool

property min_version

The minimum TLS version used for termination and advertised to the client during the TLS handshake. if unspecified, ngrok will choose an industry-safe default. This value must be null if terminate_at is set to upstream.

Return type

str

property terminate_at

edge if the ngrok edge should terminate TLS traffic, upstream if TLS traffic should be passed through to the upstream ngrok agent / application server for termination. if upstream is chosen, most other modules will be disallowed because they rely on the ngrok edge being able to access the underlying traffic.

Return type

str

class ngrok.datatypes.EndpointWebhookValidation(client, props)[source]
property enabled

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

Return type

bool

property provider

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, SENDGRID.

Return type

str

property secret

a string secret used to validate requests from the given provider. All providers except AWS SNS require a secret

Return type

str

class ngrok.datatypes.EventDestination(client, props)[source]
property created_at

Timestamp when the Event Destination was created, RFC 3339 format.

Return type

str

delete()[source]
property description

Human-readable description of the Event Destination. Optional, max 255 bytes.

Return type

str

property format

The output format you would like to serialize events into when sending to their target. Currently the only accepted value is JSON.

Return type

str

property id

Unique identifier for this Event Destination.

Return type

str

property metadata

Arbitrary user-defined machine-readable data of this Event Destination. Optional, max 4096 bytes.

Return type

str

property target

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.

Return type

EventTarget

property uri

URI of the Event Destination API resource.

Return type

str

class ngrok.datatypes.EventDestinationList(client, props)[source]
property event_destinations

The list of all Event Destinations on this account.

Return type

Sequence[EventDestination]

property next_page_uri

URI of the next page, or null if there is no next page.

Return type

str

property uri

URI of the Event Destinations list API resource.

Return type

str

class ngrok.datatypes.EventSource(client, props)[source]
property type

Type of event for which an event subscription will trigger

Return type

str

property uri

URI of the Event Source API resource.

Return type

str

class ngrok.datatypes.EventSourceList(client, props)[source]
property sources

The list of all Event Sources for an Event Subscription

Return type

Sequence[EventSource]

property uri

URI of the next page, or null if there is no next page.

Return type

str

class ngrok.datatypes.EventSourceReplace(client, props)[source]
property type

Type of event for which an event subscription will trigger

Return type

str

class ngrok.datatypes.EventStream(client, props)[source]
property created_at

Timestamp when the Event Stream was created, RFC 3339 format.

Return type

str

delete()[source]
property description

Human-readable description of the Event Stream. Optional, max 255 bytes.

Return type

str

property destination_ids

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.

Return type

Sequence[str]

property event_type

The protocol that determines which events will be collected. Supported values are tcp_connection_closed and http_request_complete.

Return type

str

property fields

A list of protocol-specific fields you want to collect on each event.

Return type

Sequence[str]

property id

Unique identifier for this Event Stream.

Return type

str

property metadata

Arbitrary user-defined machine-readable data of this Event Stream. Optional, max 4096 bytes.

Return type

str

property sampling_rate

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.

Return type

float

update(metadata=None, description=None, fields=None, destination_ids=None, sampling_rate=None)[source]
property uri

URI of the Event Stream API resource.

Return type

str

class ngrok.datatypes.EventStreamList(client, props)[source]
property event_streams

The list of all Event Streams on this account.

Return type

Sequence[EventStream]

property next_page_uri

URI of the next page, or null if there is no next page.

Return type

str

property uri

URI of the Event Stream list API resource.

Return type

str

class ngrok.datatypes.EventSubscription(client, props)[source]
property created_at

When the Event Subscription was created (RFC 3339 format).

Return type

str

delete()[source]
property description

Arbitrary customer supplied information intended to be human readable. Optional, max 255 chars.

Return type

str

property destinations

Destinations to which these events will be sent

Return type

Sequence[Ref]

property id

Unique identifier for this Event Subscription.

Return type

str

property metadata

Arbitrary customer supplied information intended to be machine readable. Optional, max 4096 chars.

Return type

str

property sources

Sources containing the types for which this event subscription will trigger

Return type

Sequence[EventSource]

property uri

URI of the Event Subscription API resource.

Return type

str

class ngrok.datatypes.EventSubscriptionList(client, props)[source]
property event_subscriptions

The list of all Event Subscriptions on this account.

Return type

Sequence[EventSubscription]

property next_page_uri

URI of next page, or null if there is no next page.

Return type

str

property uri

URI of the Event Subscriptions list API resource.

Return type

str

class ngrok.datatypes.EventTarget(client, props)[source]
property cloudwatch_logs

Configuration used to send events to Amazon CloudWatch Logs.

Return type

EventTargetCloudwatchLogs

property firehose

Configuration used to send events to Amazon Kinesis Data Firehose.

Return type

EventTargetFirehose

property kinesis

Configuration used to send events to Amazon Kinesis.

Return type

EventTargetKinesis

class ngrok.datatypes.EventTargetCloudwatchLogs(client, props)[source]
property auth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

Return type

AWSAuth

property log_group_arn

An Amazon Resource Name specifying the CloudWatch Logs group to deposit events into.

Return type

str

class ngrok.datatypes.EventTargetFirehose(client, props)[source]
property auth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

Return type

AWSAuth

property delivery_stream_arn

An Amazon Resource Name specifying the Firehose delivery stream to deposit events into.

Return type

str

class ngrok.datatypes.EventTargetKinesis(client, props)[source]
property auth

Configuration for how to authenticate into your AWS account. Exactly one of role or creds should be configured.

Return type

AWSAuth

property stream_arn

An Amazon Resource Name specifying the Kinesis stream to deposit events into.

Return type

str

class ngrok.datatypes.IPPolicy(client, props)[source]
property action

the IP policy action. Supported values are allow or deny

Return type

str

property created_at

timestamp when the IP policy was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of the source IPs of this IP policy. optional, max 255 bytes.

Return type

str

property id

unique identifier for this IP policy

Return type

str

property metadata

arbitrary user-defined machine-readable data of this IP policy. optional, max 4096 bytes.

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the IP Policy API resource

Return type

str

class ngrok.datatypes.IPPolicyList(client, props)[source]
property ip_policies

the list of all IP policies on this account

Return type

Sequence[IPPolicy]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the IP policy list API resource

Return type

str

class ngrok.datatypes.IPPolicyRule(client, props)[source]
property cidr

an IP or IP range specified in CIDR notation. IPv4 and IPv6 are both supported.

Return type

str

property created_at

timestamp when the IP policy rule was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of the source IPs of this IP rule. optional, max 255 bytes.

Return type

str

property id

unique identifier for this IP policy rule

Return type

str

property ip_policy

object describing the IP policy this IP Policy Rule belongs to

Return type

Ref

property metadata

arbitrary user-defined machine-readable data of this IP policy rule. optional, max 4096 bytes.

Return type

str

update(description=None, metadata=None, cidr=None)[source]
property uri

URI of the IP policy rule API resource

Return type

str

class ngrok.datatypes.IPPolicyRuleList(client, props)[source]
property ip_policy_rules

the list of all IP policy rules on this account

Return type

Sequence[IPPolicyRule]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the IP policy rule list API resource

Return type

str

class ngrok.datatypes.IPRestriction(client, props)[source]
property created_at

timestamp when the IP restriction was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of this IP restriction. optional, max 255 bytes.

Return type

str

property enforced

true if the IP restriction will be enforced. if false, only warnings will be issued

Return type

bool

property id

unique identifier for this IP restriction

Return type

str

property ip_policies

the set of IP policies that are used to enforce the restriction

Return type

Sequence[Ref]

property metadata

arbitrary user-defined machine-readable data of this IP restriction. optional, max 4096 bytes.

Return type

str

property type

the type of IP restriction. this defines what traffic will be restricted with the attached policies. four values are currently supported: dashboard, api, agent, and endpoints

Return type

str

property uri

URI of the IP restriction API resource

Return type

str

class ngrok.datatypes.IPRestrictionList(client, props)[source]
property ip_restrictions

the list of all IP restrictions on this account

Return type

Sequence[IPRestriction]

property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the IP resrtrictions list API resource

Return type

str

class ngrok.datatypes.IPWhitelistEntry(client, props)[source]
property created_at

timestamp when the IP whitelist entry was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of the source IPs for this IP whitelist entry. optional, max 255 bytes.

Return type

str

property id

unique identifier for this IP whitelist entry

Return type

str

property ip_net

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

Return type

str

property metadata

arbitrary user-defined machine-readable data of this IP whitelist entry. optional, max 4096 bytes.

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the IP whitelist entry API resource

Return type

str

class ngrok.datatypes.IPWhitelistEntryList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property uri

URI of the IP whitelist API resource

Return type

str

property whitelist

the list of all IP whitelist entries on this account

Return type

Sequence[IPWhitelistEntry]

class ngrok.datatypes.Ref(client, props)[source]
property id

a resource identifier

Return type

str

property uri

a uri for locating a resource

Return type

str

class ngrok.datatypes.ReservedAddr(client, props)[source]
property addr

hostname:port of the reserved address that was assigned at creation time

Return type

str

property created_at

timestamp when the reserved address was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of what this reserved address will be used for

Return type

str

property endpoint_configuration

object reference to the endpoint configuration that will be applied to traffic to this address

Return type

Ref

property id

unique reserved address resource identifier

Return type

str

property metadata

arbitrary user-defined machine-readable data of this reserved address. Optional, max 4096 bytes.

Return type

str

property region

reserve the address in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

Return type

str

property uri

URI of the reserved address API resource

Return type

str

class ngrok.datatypes.ReservedAddrList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property reserved_addrs

the list of all reserved addresses on this account

Return type

Sequence[ReservedAddr]

property uri

URI of the reserved address list API resource

Return type

str

class ngrok.datatypes.ReservedDomain(client, props)[source]
property certificate

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.

Return type

Ref

property certificate_management_policy

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

Return type

ReservedDomainCertPolicy

property certificate_management_status

status of the automatic certificate management for this domain, or null if automatic management is disabled

Return type

ReservedDomainCertStatus

property cname_target

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io

Return type

str

property created_at

timestamp when the reserved domain was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of what this reserved domain will be used for

Return type

str

property domain

hostname of the reserved domain

Return type

str

property http_endpoint_configuration

object referencing the endpoint configuration applied to http traffic on this domain

Return type

Ref

property https_endpoint_configuration

object referencing the endpoint configuration applied to https traffic on this domain

Return type

Ref

property id

unique reserved domain resource identifier

Return type

str

property metadata

arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.

Return type

str

property region

reserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)

Return type

str

property uri

URI of the reserved domain API resource

Return type

str

class ngrok.datatypes.ReservedDomainCertJob(client, props)[source]
property error_code

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).

Return type

str

property msg

a message describing the current status or error

Return type

str

property ns_targets

if present, indicates the dns nameservers that the user must configure to complete the provisioning process of a wildcard certificate

Return type

Sequence[ReservedDomainCertNSTarget]

property retries_at

timestamp when the provisioning job will be retried

Return type

str

property started_at

timestamp when the provisioning job started, RFC 3339 format

Return type

str

class ngrok.datatypes.ReservedDomainCertNSTarget(client, props)[source]
property nameservers

the nameservers the user must add

Return type

Sequence[str]

property zone

the zone that the nameservers need to be applied to

Return type

str

class ngrok.datatypes.ReservedDomainCertPolicy(client, props)[source]
property authority

certificate authority to request certificates from. The only supported value is letsencrypt.

Return type

str

property private_key_type

type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Return type

str

class ngrok.datatypes.ReservedDomainCertStatus(client, props)[source]
property provisioning_job

status of the certificate provisioning job, or null if the certificiate isn’t being provisioned or renewed

Return type

ReservedDomainCertJob

property renews_at

timestamp when the next renewal will be requested, RFC 3339 format

Return type

str

class ngrok.datatypes.ReservedDomainList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property reserved_domains

the list of all reserved domains on this account

Return type

Sequence[ReservedDomain]

property uri

URI of the reserved domain list API resource

Return type

str

class ngrok.datatypes.SSHCertificateAuthority(client, props)[source]
property created_at

timestamp when the SSH Certificate Authority API resource was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of this SSH Certificate Authority. optional, max 255 bytes.

Return type

str

property id

unique identifier for this SSH Certificate Authority

Return type

str

property key_type

the type of private key for this SSH Certificate Authority

Return type

str

property metadata

arbitrary user-defined machine-readable data of this SSH Certificate Authority. optional, max 4096 bytes.

Return type

str

property public_key

raw public key for this SSH Certificate Authority

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the SSH Certificate Authority API resource

Return type

str

class ngrok.datatypes.SSHCertificateAuthorityList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property ssh_certificate_authorities

the list of all certificate authorities on this account

Return type

Sequence[SSHCertificateAuthority]

property uri

URI of the certificates authorities list API resource

Return type

str

class ngrok.datatypes.SSHCredential(client, props)[source]
property acl

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.

Return type

Sequence[str]

property created_at

timestamp when the ssh credential was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of who or what will use the ssh credential to authenticate. Optional, max 255 bytes.

Return type

str

property id

unique ssh credential resource identifier

Return type

str

property metadata

arbitrary user-defined machine-readable data of this ssh credential. Optional, max 4096 bytes.

Return type

str

property public_key

the PEM-encoded public key of the SSH keypair that will be used to authenticate

Return type

str

update(description=None, metadata=None, acl=None)[source]
property uri

URI of the ssh credential API resource

Return type

str

class ngrok.datatypes.SSHCredentialList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property ssh_credentials

the list of all ssh credentials on this account

Return type

Sequence[SSHCredential]

property uri

URI of the ssh credential list API resource

Return type

str

class ngrok.datatypes.SSHHostCertificate(client, props)[source]
property certificate

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

Return type

str

property created_at

timestamp when the SSH Host Certificate API resource was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of this SSH Host Certificate. optional, max 255 bytes.

Return type

str

property id

unique identifier for this SSH Host Certificate

Return type

str

property key_type

the key type of the public_key, one of rsa, ecdsa or ed25519

Return type

str

property metadata

arbitrary user-defined machine-readable data of this SSH Host Certificate. optional, max 4096 bytes.

Return type

str

property principals

the list of principals included in the ssh host certificate. This is the list of hostnames and/or IP addresses that are authorized to serve SSH traffic with this certificate. Dangerously, if no principals are specified, this certificate is considered valid for all hosts.

Return type

Sequence[str]

property public_key

a public key in OpenSSH Authorized Keys format that this certificate signs

Return type

str

property ssh_certificate_authority_id

the ssh certificate authority that is used to sign this ssh host certificate

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the SSH Host Certificate API resource

Return type

str

property valid_after

the time when the ssh host certificate becomes valid, in RFC 3339 format.

Return type

str

property valid_until

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

Return type

str

class ngrok.datatypes.SSHHostCertificateList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property ssh_host_certificates

the list of all ssh host certificates on this account

Return type

Sequence[SSHHostCertificate]

property uri

URI of the ssh host certificates list API resource

Return type

str

class ngrok.datatypes.SSHUserCertificate(client, props)[source]
property certificate

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

Return type

str

property created_at

timestamp when the SSH User Certificate API resource was created, RFC 3339 format

Return type

str

property critical_options

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 <https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys>`_ for additional details.

Return type

Mapping[str, str]

delete()[source]
property description

human-readable description of this SSH User Certificate. optional, max 255 bytes.

Return type

str

property extensions

A map of extensions included in the certificate. Extensions are additional metadata that can be interpreted by the SSH server for any purpose. These can be used to permit or deny the ability to open a terminal, do port forwarding, x11 forwarding, and more. If unspecified, the certificate will include limited permissions with the following extension map: {"permit-pty": "", "permit-user-rc": ""} OpenSSH understands a number of predefined extensions. See the OpenSSH certificate protocol spec <https://github.com/openssh/openssh-portable/blob/master/PROTOCOL.certkeys>`_ for additional details.

Return type

Mapping[str, str]

property id

unique identifier for this SSH User Certificate

Return type

str

property key_type

the key type of the public_key, one of rsa, ecdsa or ed25519

Return type

str

property metadata

arbitrary user-defined machine-readable data of this SSH User Certificate. optional, max 4096 bytes.

Return type

str

property principals

the list of principals included in the ssh user certificate. This is the list of usernames that the certificate holder may sign in as on a machine authorizinig the signing certificate authority. Dangerously, if no principals are specified, this certificate may be used to log in as any user.

Return type

Sequence[str]

property public_key

a public key in OpenSSH Authorized Keys format that this certificate signs

Return type

str

property ssh_certificate_authority_id

the ssh certificate authority that is used to sign this ssh user certificate

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the SSH User Certificate API resource

Return type

str

property valid_after

the time when the ssh host certificate becomes valid, in RFC 3339 format.

Return type

str

property valid_until

the time after which the ssh host certificate becomes invalid, in RFC 3339 format. the OpenSSH certificates RFC calls this valid_before.

Return type

str

class ngrok.datatypes.SSHUserCertificateList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property ssh_user_certificates

the list of all ssh user certificates on this account

Return type

Sequence[SSHUserCertificate]

property uri

URI of the ssh user certificates list API resource

Return type

str

class ngrok.datatypes.TLSCertificate(client, props)[source]
property certificate_pem

chain of PEM-encoded certificates, leaf first. See Certificate Bundles <https://ngrok.com/docs/api#tls-certificates-pem>`_.

Return type

str

property created_at

timestamp when the TLS certificate was created, RFC 3339 format

Return type

str

delete()[source]
property description

human-readable description of this TLS certificate. optional, max 255 bytes.

Return type

str

property extended_key_usages

extended set of actions the private key of this TLS certificate can be used for

Return type

Sequence[str]

property id

unique identifier for this TLS certificate

Return type

str

property issued_at

timestamp (in RFC 3339 format) when this TLS certificate was issued automatically, or null if this certificate was user-uploaded

Return type

str

property issuer_common_name

issuer common name from the leaf of this TLS certificate

Return type

str

property key_usages

set of actions the private key of this TLS certificate can be used for

Return type

Sequence[str]

property metadata

arbitrary user-defined machine-readable data of this TLS certificate. optional, max 4096 bytes.

Return type

str

property not_after

timestamp when this TLS certificate becomes invalid, RFC 3339 format

Return type

str

property not_before

timestamp when this TLS certificate becomes valid, RFC 3339 format

Return type

str

property private_key_type

type of the private key of this TLS certificate. One of rsa, ecdsa, or ed25519.

Return type

str

property serial_number

serial number of the leaf of this TLS certificate

Return type

str

property subject_alternative_names

subject alternative names (SANs) from the leaf of this TLS certificate

Return type

TLSCertificateSANs

property subject_common_name

subject common name from the leaf of this TLS certificate

Return type

str

property subject_country

subject country from the leaf of this TLS certificate

Return type

str

property subject_locality

subject locality from the leaf of this TLS certificate

Return type

str

property subject_organization

subject organization from the leaf of this TLS certificate

Return type

str

property subject_organizational_unit

subject organizational unit from the leaf of this TLS certificate

Return type

str

property subject_province

subject province from the leaf of this TLS certificate

Return type

str

update(description=None, metadata=None)[source]
property uri

URI of the TLS certificate API resource

Return type

str

class ngrok.datatypes.TLSCertificateList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property tls_certificates

the list of all TLS certificates on this account

Return type

Sequence[TLSCertificate]

property uri

URI of the TLS certificates list API resource

Return type

str

class ngrok.datatypes.TLSCertificateSANs(client, props)[source]
property dns_names

set of additional domains (including wildcards) this TLS certificate is valid for

Return type

Sequence[str]

property ips

set of IP addresses this TLS certificate is also valid for

Return type

Sequence[str]

class ngrok.datatypes.Tunnel(client, props)[source]
property id

unique tunnel resource identifier

Return type

str

property metadata

user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option <https://ngrok.com/docs#tunnel-definitions-metadata>`_ In API version 0, this value was instead pulled from the top-level metadata configuration option <https://ngrok.com/docs#config_metadata>`_.

Return type

str

property proto

tunnel protocol. one of http, https, tcp or tls

Return type

str

property public_url

URL of the tunnel’s public endpoint

Return type

str

property region

identifier of tune region where the tunnel is running

Return type

str

property started_at

timestamp when the tunnel was initiated in RFC 3339 format

Return type

str

property tunnel_session

reference object pointing to the tunnel session on which this tunnel was started

Return type

Ref

class ngrok.datatypes.TunnelList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property tunnels

the list of all online tunnels on this account

Return type

Sequence[Tunnel]

property uri

URI of the tunnels list API resource

Return type

str

class ngrok.datatypes.TunnelSession(client, props)[source]
property agent_version

version of the ngrok agent that started this ngrok tunnel session

Return type

str

property credential

reference to the tunnel credential or ssh credential used by the ngrok agent to start this tunnel session

Return type

Ref

property id

unique tunnel session resource identifier

Return type

str

property ip

source ip address of the tunnel session

Return type

str

property metadata

arbitrary user-defined data specified in the metadata property in the ngrok configuration file. See the metadata configuration option

Return type

str

property os

operating system of the host the ngrok agent is running on

Return type

str

property region

the ngrok region identifier in which this tunnel session was started

Return type

str

property started_at

time when the tunnel session first connected to the ngrok servers

Return type

str

property transport

the transport protocol used to start the tunnel session. Either ngrok/v2 or ssh

Return type

str

property uri

URI to the API resource of the tunnel session

Return type

str

class ngrok.datatypes.TunnelSessionList(client, props)[source]
property next_page_uri

URI of the next page, or null if there is no next page

Return type

str

property tunnel_sessions

list of all tunnel sessions on this account

Return type

Sequence[TunnelSession]

property uri

URI to the API resource of the tunnel session list

Return type

str