Datatypes

This module contains all datatypes returned by the ngrok API.

class ngrok.datatypes.APIKey(client, props)

property created_at: datetime

timestamp when the api key was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique API key resource identifier

Return type:

str

property metadata: str

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

Return type:

str

property owner_id: str

If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Return type:

str

property token: str

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)

property uri: str

URI to the API resource of this API key

Return type:

str

class ngrok.datatypes.APIKeyList(client, props)

property keys: Sequence[APIKey]

the list of API keys for this account

Return type:

Sequence[APIKey]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the API keys list API resource

Return type:

str

class ngrok.datatypes.AWSAuth(client, props)

property creds: AWSCredentials

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

Return type:

AWSCredentials

property role: AWSRole

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)

property aws_access_key_id: str

The ID portion of an AWS access key.

Return type:

str

property aws_secret_access_key: str

The secret portion of an AWS access key.

Return type:

str

class ngrok.datatypes.AWSRole(client, props)

property role_arn: str

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)

property created_at: datetime

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

Return type:

datetime

property hostnames: Sequence[AbuseReportHostname]

an array of hostname statuses related to the report

Return type:

Sequence[AbuseReportHostname]

property id: str

ID of the abuse report

Return type:

str

property metadata: str

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

Return type:

str

property status: str

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

Return type:

str

property uri: str

URI of the abuse report API resource

Return type:

str

property urls: Sequence[str]

a list of URLs containing suspected abusive content

Return type:

Sequence[str]

class ngrok.datatypes.AbuseReportHostname(client, props)

property hostname: str

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

Return type:

str

property status: str

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

Return type:

str

class ngrok.datatypes.AgentIngress(client, props)

property certificate_management_policy: AgentIngressCertPolicy

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

Return type:

AgentIngressCertPolicy

property certificate_management_status: AgentIngressCertStatus

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

Return type:

AgentIngressCertStatus

property created_at: datetime

timestamp when the Agent Ingress was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of the use of this Agent Ingress. optional, max 255 bytes.

Return type:

str

property domain: str

the domain that you own to be used as the base domain name to generate regional agent ingress domains.

Return type:

str

property id: str

unique Agent Ingress resource identifier

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes

Return type:

str

property ns_targets: Sequence[str]

a list of target values to use as the values of NS records for the domain property these values will delegate control over the domain to ngrok

Return type:

Sequence[str]

property region_domains: Sequence[str]

a list of regional agent ingress domains that are subdomains of the value of domain this value may increase over time as ngrok adds more regions

Return type:

Sequence[str]

update(description=None, metadata=None, certificate_management_policy=None)

property uri: str

URI to the API resource of this Agent ingress

Return type:

str

class ngrok.datatypes.AgentIngressCertJob(client, props)

property error_code: str

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: str

a message describing the current status or error

Return type:

str

property retries_at: datetime

timestamp when the provisioning job will be retried

Return type:

datetime

property started_at: datetime

timestamp when the provisioning job started, RFC 3339 format

Return type:

datetime

class ngrok.datatypes.AgentIngressCertPolicy(client, props)

property authority: str

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

Return type:

str

property private_key_type: str

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

Return type:

str

class ngrok.datatypes.AgentIngressCertStatus(client, props)

property provisioning_job: AgentIngressCertJob

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

Return type:

AgentIngressCertJob

property renews_at: datetime

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

Return type:

datetime

class ngrok.datatypes.AgentIngressList(client, props)

property ingresses: Sequence[AgentIngress]

the list of Agent Ingresses owned by this account

Return type:

Sequence[AgentIngress]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the Agent Ingress list API resource

Return type:

str

class ngrok.datatypes.ApplicationSession(client, props)

property application_user: Ref

application user this session is associated with

Return type:

Ref

property browser_session: BrowserSession

browser session details of the application session

Return type:

BrowserSession

property created_at: datetime

timestamp when the user was created in RFC 3339 format

Return type:

datetime

delete()

property edge: Ref

edge this session is associated with, null if the endpoint is agent-initiated

Return type:

Ref

property endpoint: Ref

ephemeral endpoint this session is associated with

Return type:

Ref

property expires_at: datetime

timestamp when session expires in RFC 3339 format

Return type:

datetime

property id: str

unique application session resource identifier

Return type:

str

property last_active: datetime

timestamp when the user was last active in RFC 3339 format

Return type:

datetime

property public_url: str

URL of the hostport served by this endpoint

Return type:

str

property route: Ref

route this session is associated with, null if the endpoint is agent-initiated

Return type:

Ref

property uri: str

URI of the application session API resource

Return type:

str

class ngrok.datatypes.ApplicationSessionList(client, props)

property application_sessions: Sequence[ApplicationSession]

list of all application sessions on this account

Return type:

Sequence[ApplicationSession]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the application session list API resource

Return type:

str

class ngrok.datatypes.ApplicationUser(client, props)

property created_at: datetime

timestamp when the user was created in RFC 3339 format

Return type:

datetime

delete()

property email: str

user email

Return type:

str

property id: str

unique application user resource identifier

Return type:

str

property identity_provider: IdentityProvider

identity provider that the user authenticated with

Return type:

IdentityProvider

property last_active: datetime

timestamp when the user was last active in RFC 3339 format

Return type:

datetime

property last_login: datetime

timestamp when the user last signed-in in RFC 3339 format

Return type:

datetime

property name: str

user common name

Return type:

str

property provider_user_id: str

unique user identifier

Return type:

str

property uri: str

URI of the application user API resource

Return type:

str

property username: str

user username

Return type:

str

class ngrok.datatypes.ApplicationUserList(client, props)

property application_users: Sequence[ApplicationUser]

list of all application users on this account

Return type:

Sequence[ApplicationUser]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the application user list API resource

Return type:

str

class ngrok.datatypes.BotUser(client, props)

property active: bool

whether or not the bot is active

Return type:

bool

property created_at: datetime

timestamp when the api key was created, RFC 3339 format

Return type:

datetime

delete()

property id: str

unique API key resource identifier

Return type:

str

property name: str

human-readable name used to identify the bot

Return type:

str

update(name=None, active=None)

property uri: str

URI to the API resource of this bot user

Return type:

str

class ngrok.datatypes.BotUserList(client, props)

property bot_users: Sequence[BotUser]

the list of all bot users on this account

Return type:

Sequence[BotUser]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the bot users list API resource

Return type:

str

class ngrok.datatypes.BrowserSession(client, props)

property ip_address: str

IP address

Return type:

str

property location: Location

IP geolocation data

Return type:

Location

property user_agent: UserAgent

HTTP User-Agent data

Return type:

UserAgent

class ngrok.datatypes.CertificateAuthority(client, props)

property ca_pem: str

raw PEM of the Certificate Authority

Return type:

str

property created_at: datetime

timestamp when the Certificate Authority was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property extended_key_usages: Sequence[str]

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

Return type:

Sequence[str]

property id: str

unique identifier for this Certificate Authority

Return type:

str

property key_usages: Sequence[str]

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

Return type:

Sequence[str]

property metadata: str

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

Return type:

str

property not_after: datetime

timestamp when this Certificate Authority becomes invalid, RFC 3339 format

Return type:

datetime

property not_before: datetime

timestamp when this Certificate Authority becomes valid, RFC 3339 format

Return type:

datetime

property subject_common_name: str

subject common name of the Certificate Authority

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the Certificate Authority API resource

Return type:

str

class ngrok.datatypes.CertificateAuthorityList(client, props)

property certificate_authorities: Sequence[CertificateAuthority]

the list of all certificate authorities on this account

Return type:

Sequence[CertificateAuthority]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the certificates authorities list API resource

Return type:

str

class ngrok.datatypes.Credential(client, props)

property acl: Sequence[str]

optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:*.example.com which will allow x.example.com, y.example.com, *.example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:*=example which will allow x=example, y=example, etc. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

Return type:

Sequence[str]

property created_at: datetime

timestamp when the tunnel credential was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique tunnel credential resource identifier

Return type:

str

property metadata: str

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

Return type:

str

property owner_id: str

If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Return type:

str

property token: str

the credential’s authtoken that can be used to authenticate an ngrok agent. 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)

property uri: str

URI of the tunnel credential API resource

Return type:

str

class ngrok.datatypes.CredentialList(client, props)

property credentials: Sequence[Credential]

the list of all tunnel credentials on this account

Return type:

Sequence[Credential]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the tunnel credential list API resource

Return type:

str

class ngrok.datatypes.Endpoint(client, props)

property bindings: Sequence[str]

the bindings associated with this endpoint

Return type:

Sequence[str]

property created_at: datetime

timestamp when the endpoint was created in RFC 3339 format

Return type:

datetime

delete()

property description: str

user-supplied description of the associated tunnel

Return type:

str

property domain: Ref

the domain reserved for this endpoint

Return type:

Ref

property edge: Ref

the edge serving requests to this endpoint, if this is an edge endpoint

Return type:

Ref

property host: str

Return type:

str

property hostport: str

hostport served by this endpoint (hostname:port) -> soon to be deprecated

Return type:

str

property id: str

unique endpoint resource identifier

Return type:

str

property metadata: str

user-supplied metadata of the associated tunnel or edge object

Return type:

str

property name: str

user supplied name for the endpoint

Return type:

str

property pooling_enabled: bool

whether the endpoint allows pooling

Return type:

bool

property port: int

Return type:

int

property principal: Ref

The ID of the owner (bot or user) that owns this endpoint

Return type:

Ref

property proto: str

protocol served by this endpoint. one of http, https, tcp, or tls

Return type:

str

property public_url: str

URL of the hostport served by this endpoint

Return type:

str

property region: str

identifier of the region this endpoint belongs to

Return type:

str

property scheme: str

Return type:

str

property tcp_addr: Ref

the address reserved for this endpoint

Return type:

Ref

property traffic_policy: str

The traffic policy attached to this endpoint

Return type:

str

property tunnel: Ref

the tunnel serving requests to this endpoint, if this is an ephemeral endpoint

Return type:

Ref

property tunnel_session: Ref

The tunnel session of the agent for this endpoint

Return type:

Ref

property type: str

whether the endpoint is ephemeral (served directly by an agent-initiated tunnel) or edge (served by an edge) or cloud (represents a cloud endpoint)

Return type:

str

update(url=None, traffic_policy=None, description=None, metadata=None, bindings=None, pooling_enabled=False)

property updated_at: datetime

timestamp when the endpoint was updated in RFC 3339 format

Return type:

datetime

property upstream_protocol: str

the protocol the agent uses to forward with

Return type:

str

property upstream_url: str

the local address the tunnel forwards to

Return type:

str

property uri: str

URI of the clep API resource

Return type:

str

property url: str

the url of the endpoint

Return type:

str

class ngrok.datatypes.EndpointBackend(client, props)

property backend: Ref

backend to be used to back this endpoint

Return type:

Ref

property enabled: bool

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

Return type:

bool

class ngrok.datatypes.EndpointBackendMutate(client, props)

property backend_id: str

backend to be used to back this endpoint

Return type:

str

property enabled: bool

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

Return type:

bool

class ngrok.datatypes.EndpointCircuitBreaker(client, props)

property enabled: bool

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

Return type:

bool

property error_threshold_percentage: float

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

Return type:

float

property num_buckets: int

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

Return type:

int

property rolling_window: int

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

Return type:

int

property tripped_duration: timedelta

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

Return type:

timedelta

property volume_threshold: int

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)

property enabled: bool

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

Return type:

bool

class ngrok.datatypes.EndpointIPPolicy(client, props)

property enabled: bool

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

Return type:

bool

property ip_policies: Sequence[Ref]

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

Return type:

Sequence[Ref]

class ngrok.datatypes.EndpointIPPolicyMutate(client, props)

property enabled: bool

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

Return type:

bool

property ip_policy_ids: Sequence[str]

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.EndpointList(client, props)

property endpoints: Sequence[Endpoint]

the list of all active endpoints on this account

Return type:

Sequence[Endpoint]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the endpoints list API resource

Return type:

str

class ngrok.datatypes.EndpointMutualTLS(client, props)

property certificate_authorities: Sequence[Ref]

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: bool

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)

property certificate_authority_ids: Sequence[str]

list of certificate authorities that will be used to validate the TLS client certificate presented by the initiator of the TLS connection

Return type:

Sequence[str]

property enabled: bool

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)

property auth_check_interval: int

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: str

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

Return type:

str

property enabled: bool

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

Return type:

bool

property inactivity_timeout: int

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: timedelta

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

Return type:

timedelta

property options_passthrough: bool

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

Return type:

bool

property provider: EndpointOAuthProvider

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.EndpointOAuthAmazon(client, props)

property client_id: str

Return type:

str

property client_secret: str

Return type:

str

property email_addresses: Sequence[str]

Return type:

Sequence[str]

property email_domains: Sequence[str]

Return type:

Sequence[str]

property scopes: Sequence[str]

Return type:

Sequence[str]

class ngrok.datatypes.EndpointOAuthFacebook(client, props)

property client_id: str

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: str

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: Sequence[str]

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: Sequence[str]

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

Return type:

Sequence[str]

property scopes: Sequence[str]

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)

property client_id: str

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: str

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: Sequence[str]

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: Sequence[str]

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

Return type:

Sequence[str]

property organizations: Sequence[str]

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: Sequence[str]

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: Sequence[str]

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.EndpointOAuthGitLab(client, props)

property client_id: str

Return type:

str

property client_secret: str

Return type:

str

property email_addresses: Sequence[str]

Return type:

Sequence[str]

property email_domains: Sequence[str]

Return type:

Sequence[str]

property scopes: Sequence[str]

Return type:

Sequence[str]

class ngrok.datatypes.EndpointOAuthGoogle(client, props)

property client_id: str

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: str

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: Sequence[str]

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: Sequence[str]

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

Return type:

Sequence[str]

property scopes: Sequence[str]

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.EndpointOAuthLinkedIn(client, props)

property client_id: str

Return type:

str

property client_secret: str

Return type:

str

property email_addresses: Sequence[str]

Return type:

Sequence[str]

property email_domains: Sequence[str]

Return type:

Sequence[str]

property scopes: Sequence[str]

Return type:

Sequence[str]

class ngrok.datatypes.EndpointOAuthMicrosoft(client, props)

property client_id: str

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: str

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: Sequence[str]

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: Sequence[str]

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

Return type:

Sequence[str]

property scopes: Sequence[str]

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)

property amazon: EndpointOAuthAmazon

configuration for using amazon as the identity provider

Return type:

EndpointOAuthAmazon

property facebook: EndpointOAuthFacebook

configuration for using facebook as the identity provider

Return type:

EndpointOAuthFacebook

property github: EndpointOAuthGitHub

configuration for using github as the identity provider

Return type:

EndpointOAuthGitHub

property gitlab: EndpointOAuthGitLab

configuration for using gitlab as the identity provider

Return type:

EndpointOAuthGitLab

property google: EndpointOAuthGoogle

configuration for using google as the identity provider

Return type:

EndpointOAuthGoogle

property linkedin: EndpointOAuthLinkedIn

configuration for using linkedin as the identity provider

Return type:

EndpointOAuthLinkedIn

property microsoft: EndpointOAuthMicrosoft

configuration for using microsoft as the identity provider

Return type:

EndpointOAuthMicrosoft

property twitch: EndpointOAuthTwitch

configuration for using twitch as the identity provider

Return type:

EndpointOAuthTwitch

class ngrok.datatypes.EndpointOAuthTwitch(client, props)

property client_id: str

Return type:

str

property client_secret: str

Return type:

str

property email_addresses: Sequence[str]

Return type:

Sequence[str]

property email_domains: Sequence[str]

Return type:

Sequence[str]

property scopes: Sequence[str]

Return type:

Sequence[str]

class ngrok.datatypes.EndpointOIDC(client, props)

property client_id: str

The OIDC app’s client ID and OIDC audience.

Return type:

str

property client_secret: str

The OIDC app’s client secret.

Return type:

str

property cookie_prefix: str

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

Return type:

str

property enabled: bool

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

Return type:

bool

property inactivity_timeout: int

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: str

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

Return type:

str

property maximum_duration: timedelta

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

Return type:

timedelta

property options_passthrough: bool

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

Return type:

bool

property scopes: Sequence[str]

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

Return type:

Sequence[str]

class ngrok.datatypes.EndpointRequestHeaders(client, props)

property add: Mapping[str, str]

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: bool

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

Return type:

bool

property remove: Sequence[str]

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)

property add: Mapping[str, str]

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: bool

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

Return type:

bool

property remove: Sequence[str]

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)

property allow_idp_initiated: bool

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: str

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: Sequence[str]

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: str

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

Return type:

str

property enabled: bool

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

Return type:

bool

property entity_id: str

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: bool

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: str

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: int

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: timedelta

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

Return type:

timedelta

property metadata_url: str

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: str

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: bool

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

Return type:

bool

property request_signing_certificate_pem: str

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: str

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)

property allow_idp_initiated: bool

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: Sequence[str]

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: str

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

Return type:

str

property enabled: bool

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

Return type:

bool

property force_authn: bool

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: str

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: int

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: timedelta

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

Return type:

timedelta

property nameid_format: str

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: bool

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

Return type:

bool

class ngrok.datatypes.EndpointTLSTermination(client, props)

property enabled: bool

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

Return type:

bool

property min_version: str

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: str

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.EndpointTLSTerminationAtEdge(client, props)

property enabled: bool

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

Return type:

bool

property min_version: str

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

class ngrok.datatypes.EndpointTrafficPolicy(client, props)

property enabled: bool

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

Return type:

bool

property value: str

the traffic policy that should be applied to the traffic on your endpoint.

Return type:

str

class ngrok.datatypes.EndpointUserAgentFilter(client, props)

property allow: Sequence[str]

Return type:

Sequence[str]

property deny: Sequence[str]

Return type:

Sequence[str]

property enabled: bool

Return type:

bool

class ngrok.datatypes.EndpointWebhookValidation(client, props)

property enabled: bool

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

Return type:

bool

property provider: str

a string indicating which webhook provider will be sending webhooks to this endpoint. Value must be one of the supported providers defined at https://ngrok.com/docs/cloud-edge/modules/webhook-verification

Return type:

str

property secret: str

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.EndpointWebsocketTCPConverter(client, props)

property enabled: bool

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

Return type:

bool

class ngrok.datatypes.EventDestination(client, props)

property created_at: datetime

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

Return type:

datetime

delete()

property description: str

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

Return type:

str

property format: str

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: str

Unique identifier for this Event Destination.

Return type:

str

property metadata: str

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

Return type:

str

property target: EventTarget

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: str

URI of the Event Destination API resource.

Return type:

str

class ngrok.datatypes.EventDestinationList(client, props)

property event_destinations: Sequence[EventDestination]

The list of all Event Destinations on this account.

Return type:

Sequence[EventDestination]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the Event Destinations list API resource.

Return type:

str

class ngrok.datatypes.EventSource(client, props)

property type: str

Type of event for which an event subscription will trigger

Return type:

str

property uri: str

URI of the Event Source API resource.

Return type:

str

class ngrok.datatypes.EventSourceList(client, props)

property sources: Sequence[EventSource]

The list of all Event Sources for an Event Subscription

Return type:

Sequence[EventSource]

property uri: str

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

Return type:

str

class ngrok.datatypes.EventSourceReplace(client, props)

property type: str

Type of event for which an event subscription will trigger

Return type:

str

class ngrok.datatypes.EventSubscription(client, props)

property created_at: datetime

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

Return type:

datetime

delete()

property description: str

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

Return type:

str

property destinations: Sequence[Ref]

Destinations to which these events will be sent

Return type:

Sequence[Ref]

property id: str

Unique identifier for this Event Subscription.

Return type:

str

property metadata: str

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

Return type:

str

property sources: Sequence[EventSource]

Sources containing the types for which this event subscription will trigger

Return type:

Sequence[EventSource]

property uri: str

URI of the Event Subscription API resource.

Return type:

str

class ngrok.datatypes.EventSubscriptionList(client, props)

property event_subscriptions: Sequence[EventSubscription]

The list of all Event Subscriptions on this account.

Return type:

Sequence[EventSubscription]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the Event Subscriptions list API resource.

Return type:

str

class ngrok.datatypes.EventTarget(client, props)

property azure_logs_ingestion: EventTargetAzureLogsIngestion

Return type:

EventTargetAzureLogsIngestion

property cloudwatch_logs: EventTargetCloudwatchLogs

Configuration used to send events to Amazon CloudWatch Logs.

Return type:

EventTargetCloudwatchLogs

property datadog: EventTargetDatadog

Configuration used to send events to Datadog.

Return type:

EventTargetDatadog

property firehose: EventTargetFirehose

Configuration used to send events to Amazon Kinesis Data Firehose.

Return type:

EventTargetFirehose

property kinesis: EventTargetKinesis

Configuration used to send events to Amazon Kinesis.

Return type:

EventTargetKinesis

class ngrok.datatypes.EventTargetAzureLogsIngestion(client, props)

property client_id: str

Client ID for the application client

Return type:

str

property client_secret: str

Client Secret for the application client

Return type:

str

property data_collection_rule_id: str

Data collection rule immutable ID

Return type:

str

property data_collection_stream_name: str

Data collection stream name to use as destination, located inside the DCR

Return type:

str

property logs_ingestion_uri: str

Data collection endpoint logs ingestion URI

Return type:

str

property tenant_id: str

Tenant ID for the Azure account

Return type:

str

class ngrok.datatypes.EventTargetCloudwatchLogs(client, props)

property auth: AWSAuth

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: str

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

Return type:

str

class ngrok.datatypes.EventTargetDatadog(client, props)

property api_key: str

Datadog API key to use.

Return type:

str

property ddsite: str

Datadog site to send event to.

Return type:

str

property ddtags: str

Tags to send with the event.

Return type:

str

property service: str

Service name to send with the event.

Return type:

str

class ngrok.datatypes.EventTargetFirehose(client, props)

property auth: AWSAuth

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: str

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

Return type:

str

class ngrok.datatypes.EventTargetKinesis(client, props)

property auth: AWSAuth

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

Return type:

AWSAuth

property stream_arn: str

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

Return type:

str

class ngrok.datatypes.FailoverBackend(client, props)

property backends: Sequence[str]

the ids of the child backends in order

Return type:

Sequence[str]

property created_at: datetime

timestamp when the backend was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of this backend. Optional

Return type:

str

property id: str

unique identifier for this Failover backend

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this backend. Optional

Return type:

str

update(description=None, metadata=None, backends=[])

property uri: str

URI of the FailoverBackend API resource

Return type:

str

class ngrok.datatypes.FailoverBackendList(client, props)

property backends: Sequence[FailoverBackend]

the list of all Failover backends on this account

Return type:

Sequence[FailoverBackend]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the Failover backends list API resource

Return type:

str

class ngrok.datatypes.HTTPResponseBackend(client, props)

property body: str

body to return as fixed content

Return type:

str

property created_at: datetime

timestamp when the backend was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of this backend. Optional

Return type:

str

property headers: Mapping[str, str]

headers to return

Return type:

Mapping[str, str]

property id: str

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this backend. Optional

Return type:

str

property status_code: int

status code to return

Return type:

int

update(description=None, metadata=None, body=None, headers=None, status_code=None)

property uri: str

URI of the HTTPResponseBackend API resource

Return type:

str

class ngrok.datatypes.HTTPResponseBackendList(client, props)

property backends: Sequence[HTTPResponseBackend]

Return type:

Sequence[HTTPResponseBackend]

property next_page_uri: str

Return type:

str

property uri: str

Return type:

str

class ngrok.datatypes.HTTPSEdge(client, props)

property created_at: datetime

timestamp when the edge configuration was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of what this edge will be used for; optional, max 255 bytes.

Return type:

str

property hostports: Sequence[str]

hostports served by this edge

Return type:

Sequence[str]

property id: str

unique identifier of this edge

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this edge; optional, max 4096 bytes.

Return type:

str

property mutual_tls: EndpointMutualTLS

edge modules

Return type:

EndpointMutualTLS

property routes: Sequence[HTTPSEdgeRoute]

Return type:

Sequence[HTTPSEdgeRoute]

property tls_termination: EndpointTLSTermination

Return type:

EndpointTLSTermination

update(description=None, metadata=None, hostports=None, mutual_tls=None, tls_termination=None)

property uri: str

URI of the edge API resource

Return type:

str

class ngrok.datatypes.HTTPSEdgeList(client, props)

property https_edges: Sequence[HTTPSEdge]

the list of all HTTPS Edges on this account

Return type:

Sequence[HTTPSEdge]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the HTTPS Edge list API resource

Return type:

str

class ngrok.datatypes.HTTPSEdgeRoute(client, props)

property backend: EndpointBackend

backend module configuration or null

Return type:

EndpointBackend

property circuit_breaker: EndpointCircuitBreaker

circuit breaker module configuration or null

Return type:

EndpointCircuitBreaker

property compression: EndpointCompression

compression module configuration or null

Return type:

EndpointCompression

property created_at: datetime

timestamp when the edge configuration was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of what this edge will be used for; optional, max 255 bytes.

Return type:

str

property edge_id: str

unique identifier of this edge

Return type:

str

property id: str

unique identifier of this edge route

Return type:

str

property ip_restriction: EndpointIPPolicy

ip restriction module configuration or null

Return type:

EndpointIPPolicy

property match: str

Route selector: “/blog” or “example.com” or “example.com/blog”

Return type:

str

property match_type: str

Type of match to use for this route. Valid values are “exact_path” and “path_prefix”.

Return type:

str

property metadata: str

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

Return type:

str

property oauth: EndpointOAuth

oauth module configuration or null

Return type:

EndpointOAuth

property oidc: EndpointOIDC

oidc module configuration or null

Return type:

EndpointOIDC

property request_headers: EndpointRequestHeaders

request headers module configuration or null

Return type:

EndpointRequestHeaders

property response_headers: EndpointResponseHeaders

response headers module configuration or null

Return type:

EndpointResponseHeaders

property saml: EndpointSAML

saml module configuration or null

Return type:

EndpointSAML

property traffic_policy: EndpointTrafficPolicy

the traffic policy associated with this edge or null

Return type:

EndpointTrafficPolicy

update(match_type='', match='', description='', metadata='', backend=None, ip_restriction=None, circuit_breaker=None, compression=None, request_headers=None, response_headers=None, webhook_verification=None, oauth=None, saml=None, oidc=None, websocket_tcp_converter=None, user_agent_filter=None, traffic_policy=None)

property uri: str

URI of the edge API resource

Return type:

str

property user_agent_filter: EndpointUserAgentFilter

Return type:

EndpointUserAgentFilter

property webhook_verification: EndpointWebhookValidation

webhook verification module configuration or null

Return type:

EndpointWebhookValidation

property websocket_tcp_converter: EndpointWebsocketTCPConverter

websocket to tcp adapter configuration or null

Return type:

EndpointWebsocketTCPConverter

class ngrok.datatypes.IPPolicy(client, props)

property created_at: datetime

timestamp when the IP policy was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique identifier for this IP policy

Return type:

str

property metadata: str

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

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the IP Policy API resource

Return type:

str

class ngrok.datatypes.IPPolicyList(client, props)

property ip_policies: Sequence[IPPolicy]

the list of all IP policies on this account

Return type:

Sequence[IPPolicy]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the IP policy list API resource

Return type:

str

class ngrok.datatypes.IPPolicyRule(client, props)

property action: str

the action to apply to the policy rule, either allow or deny

Return type:

str

property cidr: str

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

Return type:

str

property created_at: datetime

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

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique identifier for this IP policy rule

Return type:

str

property ip_policy: Ref

object describing the IP policy this IP Policy Rule belongs to

Return type:

Ref

property metadata: str

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)

property uri: str

URI of the IP policy rule API resource

Return type:

str

class ngrok.datatypes.IPPolicyRuleList(client, props)

property ip_policy_rules: Sequence[IPPolicyRule]

the list of all IP policy rules on this account

Return type:

Sequence[IPPolicyRule]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the IP policy rule list API resource

Return type:

str

class ngrok.datatypes.IPRestriction(client, props)

property created_at: datetime

timestamp when the IP restriction was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property enforced: bool

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

Return type:

bool

property id: str

unique identifier for this IP restriction

Return type:

str

property ip_policies: Sequence[Ref]

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

Return type:

Sequence[Ref]

property metadata: str

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

Return type:

str

property type: str

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: str

URI of the IP restriction API resource

Return type:

str

class ngrok.datatypes.IPRestrictionList(client, props)

property ip_restrictions: Sequence[IPRestriction]

the list of all IP restrictions on this account

Return type:

Sequence[IPRestriction]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the IP restrictions list API resource

Return type:

str

class ngrok.datatypes.IdentityProvider(client, props)

property name: str

name of the identity provider (e.g. Google)

Return type:

str

property url: str

URL of the identity provider (e.g. https://accounts.google.com)

Return type:

str

class ngrok.datatypes.Location(client, props)

property country_code: str

ISO country code

Return type:

str

property lat_long_radius_km: int

accuracy radius of the geographical coordinates

Return type:

int

property latitude: float

geographical latitude

Return type:

float

property longitude: float

geographical longitude

Return type:

float

class ngrok.datatypes.Ref(client, props)

property id: str

a resource identifier

Return type:

str

property uri: str

a uri for locating a resource

Return type:

str

class ngrok.datatypes.ReservedAddr(client, props)

property addr: str

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

Return type:

str

property created_at: datetime

timestamp when the reserved address was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique reserved address resource identifier

Return type:

str

property metadata: str

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

Return type:

str

property region: str

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

Return type:

str

property uri: str

URI of the reserved address API resource

Return type:

str

class ngrok.datatypes.ReservedAddrList(client, props)

property next_page_uri: str

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

Return type:

str

property reserved_addrs: Sequence[ReservedAddr]

the list of all reserved addresses on this account

Return type:

Sequence[ReservedAddr]

property uri: str

URI of the reserved address list API resource

Return type:

str

class ngrok.datatypes.ReservedDomain(client, props)

property acme_challenge_cname_target: str

DNS CNAME target for the host _acme-challenge.example.com, where example.com is your reserved domain name. This is required to issue certificates for wildcard, non-ngrok reserved domains. Must be null for non-wildcard domains and ngrok subdomains.

Return type:

str

property certificate: Ref

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: ReservedDomainCertPolicy

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

Return type:

ReservedDomainCertPolicy

property certificate_management_status: ReservedDomainCertStatus

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

Return type:

ReservedDomainCertStatus

property cname_target: str

DNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)

Return type:

str

property created_at: datetime

timestamp when the reserved domain was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property domain: str

hostname of the reserved domain

Return type:

str

property id: str

unique reserved domain resource identifier

Return type:

str

property metadata: str

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

Return type:

str

property region: str

deprecated: With the launch of the ngrok Global Network domains traffic is now handled globally. This field applied only to endpoints. Note that agents may still connect to specific regions. Optional, null by default. (au, eu, ap, us, jp, in, sa)

Return type:

str

property uri: str

URI of the reserved domain API resource

Return type:

str

class ngrok.datatypes.ReservedDomainCertJob(client, props)

property error_code: str

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: str

a message describing the current status or error

Return type:

str

property retries_at: datetime

timestamp when the provisioning job will be retried

Return type:

datetime

property started_at: datetime

timestamp when the provisioning job started, RFC 3339 format

Return type:

datetime

class ngrok.datatypes.ReservedDomainCertPolicy(client, props)

property authority: str

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

Return type:

str

property private_key_type: str

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

Return type:

str

class ngrok.datatypes.ReservedDomainCertStatus(client, props)

property provisioning_job: ReservedDomainCertJob

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

Return type:

ReservedDomainCertJob

property renews_at: datetime

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

Return type:

datetime

class ngrok.datatypes.ReservedDomainList(client, props)

property next_page_uri: str

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

Return type:

str

property reserved_domains: Sequence[ReservedDomain]

the list of all reserved domains on this account

Return type:

Sequence[ReservedDomain]

property uri: str

URI of the reserved domain list API resource

Return type:

str

class ngrok.datatypes.SSHCertificateAuthority(client, props)

property created_at: datetime

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

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique identifier for this SSH Certificate Authority

Return type:

str

property key_type: str

the type of private key for this SSH Certificate Authority

Return type:

str

property metadata: str

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

Return type:

str

property public_key: str

raw public key for this SSH Certificate Authority

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the SSH Certificate Authority API resource

Return type:

str

class ngrok.datatypes.SSHCertificateAuthorityList(client, props)

property next_page_uri: str

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

Return type:

str

property ssh_certificate_authorities: Sequence[SSHCertificateAuthority]

the list of all certificate authorities on this account

Return type:

Sequence[SSHCertificateAuthority]

property uri: str

URI of the certificates authorities list API resource

Return type:

str

class ngrok.datatypes.SSHCredential(client, props)

property acl: Sequence[str]

optional list of ACL rules. If unspecified, the credential will have no restrictions. The only allowed ACL rule at this time is the bind rule. The bind rule allows the caller to restrict what domains, addresses, and labels the token is allowed to bind. For example, to allow the token to open a tunnel on example.ngrok.io your ACL would include the rule bind:example.ngrok.io. Bind rules for domains may specify a leading wildcard to match multiple domains with a common suffix. For example, you may specify a rule of bind:*.example.com which will allow x.example.com, y.example.com, *.example.com, etc. Bind rules for labels may specify a wildcard key and/or value to match multiple labels. For example, you may specify a rule of bind:*=example which will allow x=example, y=example, etc. A rule of '*' is equivalent to no acl at all and will explicitly permit all actions.

Return type:

Sequence[str]

property created_at: datetime

timestamp when the ssh credential was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique ssh credential resource identifier

Return type:

str

property metadata: str

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

Return type:

str

property owner_id: str

If supplied at credential creation, ownership will be assigned to the specified User or Bot. Only admins may specify an owner other than themselves. Defaults to the authenticated User or Bot.

Return type:

str

property public_key: str

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)

property uri: str

URI of the ssh credential API resource

Return type:

str

class ngrok.datatypes.SSHCredentialList(client, props)

property next_page_uri: str

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

Return type:

str

property ssh_credentials: Sequence[SSHCredential]

the list of all ssh credentials on this account

Return type:

Sequence[SSHCredential]

property uri: str

URI of the ssh credential list API resource

Return type:

str

class ngrok.datatypes.SSHHostCertificate(client, props)

property certificate: str

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: datetime

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

Return type:

datetime

delete()

property description: str

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

Return type:

str

property id: str

unique identifier for this SSH Host Certificate

Return type:

str

property key_type: str

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

Return type:

str

property metadata: str

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

Return type:

str

property principals: Sequence[str]

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: str

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

Return type:

str

property ssh_certificate_authority_id: str

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

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the SSH Host Certificate API resource

Return type:

str

property valid_after: datetime

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

Return type:

datetime

property valid_until: datetime

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

Return type:

datetime

class ngrok.datatypes.SSHHostCertificateList(client, props)

property next_page_uri: str

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

Return type:

str

property ssh_host_certificates: Sequence[SSHHostCertificate]

the list of all ssh host certificates on this account

Return type:

Sequence[SSHHostCertificate]

property uri: str

URI of the ssh host certificates list API resource

Return type:

str

class ngrok.datatypes.SSHUserCertificate(client, props)

property certificate: str

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: datetime

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

Return type:

datetime

property critical_options: Mapping[str, str]

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.

Return type:

Mapping[str, str]

delete()

property description: str

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

Return type:

str

property extensions: Mapping[str, str]

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.

Return type:

Mapping[str, str]

property id: str

unique identifier for this SSH User Certificate

Return type:

str

property key_type: str

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

Return type:

str

property metadata: str

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

Return type:

str

property principals: Sequence[str]

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

Return type:

Sequence[str]

property public_key: str

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

Return type:

str

property ssh_certificate_authority_id: str

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

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the SSH User Certificate API resource

Return type:

str

property valid_after: datetime

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

Return type:

datetime

property valid_until: datetime

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

Return type:

datetime

class ngrok.datatypes.SSHUserCertificateList(client, props)

property next_page_uri: str

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

Return type:

str

property ssh_user_certificates: Sequence[SSHUserCertificate]

the list of all ssh user certificates on this account

Return type:

Sequence[SSHUserCertificate]

property uri: str

URI of the ssh user certificates list API resource

Return type:

str

class ngrok.datatypes.StaticBackend(client, props)

property address: str

the address to forward to

Return type:

str

property created_at: datetime

timestamp when the backend was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of this backend. Optional

Return type:

str

property id: str

unique identifier for this static backend

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this backend. Optional

Return type:

str

property tls: StaticBackendTLS

tls configuration to use

Return type:

StaticBackendTLS

update(description=None, metadata=None, address='', tls=None)

property uri: str

URI of the StaticBackend API resource

Return type:

str

class ngrok.datatypes.StaticBackendList(client, props)

property backends: Sequence[StaticBackend]

the list of all static backends on this account

Return type:

Sequence[StaticBackend]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the static backends list API resource

Return type:

str

class ngrok.datatypes.StaticBackendTLS(client, props)

property enabled: bool

if TLS is checked

Return type:

bool

class ngrok.datatypes.TCPEdge(client, props)

property backend: EndpointBackend

edge modules

Return type:

EndpointBackend

property created_at: datetime

timestamp when the edge was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of what this edge will be used for; optional, max 255 bytes.

Return type:

str

property hostports: Sequence[str]

hostports served by this edge

Return type:

Sequence[str]

property id: str

unique identifier of this edge

Return type:

str

property ip_restriction: EndpointIPPolicy

Return type:

EndpointIPPolicy

property metadata: str

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

Return type:

str

property traffic_policy: EndpointTrafficPolicy

the traffic policy associated with this edge or null

Return type:

EndpointTrafficPolicy

update(description=None, metadata=None, hostports=None, backend=None, ip_restriction=None, traffic_policy=None)

property uri: str

URI of the edge API resource

Return type:

str

class ngrok.datatypes.TCPEdgeList(client, props)

property next_page_uri: str

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

Return type:

str

property tcp_edges: Sequence[TCPEdge]

the list of all TCP Edges on this account

Return type:

Sequence[TCPEdge]

property uri: str

URI of the TCP Edge list API resource

Return type:

str

class ngrok.datatypes.TLSCertificate(client, props)

property certificate_pem: str

chain of PEM-encoded certificates, leaf first. See Certificate Bundles.

Return type:

str

property created_at: datetime

timestamp when the TLS certificate was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

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

Return type:

str

property extended_key_usages: Sequence[str]

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

Return type:

Sequence[str]

property id: str

unique identifier for this TLS certificate

Return type:

str

property issued_at: datetime

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

Return type:

datetime

property issuer_common_name: str

issuer common name from the leaf of this TLS certificate

Return type:

str

property key_usages: Sequence[str]

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

Return type:

Sequence[str]

property metadata: str

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

Return type:

str

property not_after: datetime

timestamp when this TLS certificate becomes invalid, RFC 3339 format

Return type:

datetime

property not_before: datetime

timestamp when this TLS certificate becomes valid, RFC 3339 format

Return type:

datetime

property private_key_type: str

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

Return type:

str

property serial_number: str

serial number of the leaf of this TLS certificate

Return type:

str

property subject_alternative_names: TLSCertificateSANs

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

Return type:

TLSCertificateSANs

property subject_common_name: str

subject common name from the leaf of this TLS certificate

Return type:

str

property subject_country: str

subject country from the leaf of this TLS certificate

Return type:

str

property subject_locality: str

subject locality from the leaf of this TLS certificate

Return type:

str

property subject_organization: str

subject organization from the leaf of this TLS certificate

Return type:

str

property subject_organizational_unit: str

subject organizational unit from the leaf of this TLS certificate

Return type:

str

property subject_province: str

subject province from the leaf of this TLS certificate

Return type:

str

update(description=None, metadata=None)

property uri: str

URI of the TLS certificate API resource

Return type:

str

class ngrok.datatypes.TLSCertificateList(client, props)

property next_page_uri: str

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

Return type:

str

property tls_certificates: Sequence[TLSCertificate]

the list of all TLS certificates on this account

Return type:

Sequence[TLSCertificate]

property uri: str

URI of the TLS certificates list API resource

Return type:

str

class ngrok.datatypes.TLSCertificateSANs(client, props)

property dns_names: Sequence[str]

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

Return type:

Sequence[str]

property ips: Sequence[str]

set of IP addresses this TLS certificate is also valid for

Return type:

Sequence[str]

class ngrok.datatypes.TLSEdge(client, props)

property backend: EndpointBackend

edge modules

Return type:

EndpointBackend

property created_at: datetime

timestamp when the edge configuration was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of what this edge will be used for; optional, max 255 bytes.

Return type:

str

property hostports: Sequence[str]

hostports served by this edge

Return type:

Sequence[str]

property id: str

unique identifier of this edge

Return type:

str

property ip_restriction: EndpointIPPolicy

Return type:

EndpointIPPolicy

property metadata: str

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

Return type:

str

property mutual_tls: EndpointMutualTLS

Return type:

EndpointMutualTLS

property tls_termination: EndpointTLSTermination

Return type:

EndpointTLSTermination

property traffic_policy: EndpointTrafficPolicy

the traffic policy associated with this edge or null

Return type:

EndpointTrafficPolicy

update(description=None, metadata=None, hostports=None, backend=None, ip_restriction=None, mutual_tls=None, tls_termination=None, traffic_policy=None)

property uri: str

URI of the edge API resource

Return type:

str

class ngrok.datatypes.TLSEdgeList(client, props)

property next_page_uri: str

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

Return type:

str

property tls_edges: Sequence[TLSEdge]

the list of all TLS Edges on this account

Return type:

Sequence[TLSEdge]

property uri: str

URI of the TLS Edge list API resource

Return type:

str

class ngrok.datatypes.Tunnel(client, props)

property backends: Sequence[Ref]

tunnel group backends served by this backend tunnel

Return type:

Sequence[Ref]

property endpoint: Ref

the ephemeral endpoint this tunnel is associated with, if this is an agent-initiated tunnel

Return type:

Ref

property forwards_to: str

upstream address the ngrok agent forwards traffic over this tunnel to. this may be expressed as a URL or a network address.

Return type:

str

property id: str

unique tunnel resource identifier

Return type:

str

property labels: Mapping[str, str]

the labels the tunnel group backends will match against, if this is a backend tunnel

Return type:

Mapping[str, str]

property metadata: str

user-supplied metadata for the tunnel defined in the ngrok configuration file. See the tunnel metadata configuration option In API version 0, this value was instead pulled from the top-level metadata configuration option.

Return type:

str

property proto: str

tunnel protocol for ephemeral tunnels. one of http, https, tcp or tls

Return type:

str

property public_url: str

URL of the ephemeral tunnel’s public endpoint

Return type:

str

property region: str

identifier of tune region where the tunnel is running

Return type:

str

property started_at: datetime

timestamp when the tunnel was initiated in RFC 3339 format

Return type:

datetime

property tunnel_session: Ref

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

Return type:

Ref

class ngrok.datatypes.TunnelGroupBackend(client, props)

property created_at: datetime

timestamp when the backend was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of this backend. Optional

Return type:

str

property id: str

unique identifier for this TunnelGroup backend

Return type:

str

property labels: Mapping[str, str]

labels to watch for tunnels on, e.g. app->foo, dc->bar

Return type:

Mapping[str, str]

property metadata: str

arbitrary user-defined machine-readable data of this backend. Optional

Return type:

str

property tunnels: Sequence[Ref]

tunnels matching this backend

Return type:

Sequence[Ref]

update(description=None, metadata=None, labels={})

property uri: str

URI of the TunnelGroupBackend API resource

Return type:

str

class ngrok.datatypes.TunnelGroupBackendList(client, props)

property backends: Sequence[TunnelGroupBackend]

the list of all TunnelGroup backends on this account

Return type:

Sequence[TunnelGroupBackend]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the TunnelGroup backends list API resource

Return type:

str

class ngrok.datatypes.TunnelList(client, props)

property next_page_uri: str

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

Return type:

str

property tunnels: Sequence[Tunnel]

the list of all online tunnels on this account

Return type:

Sequence[Tunnel]

property uri: str

URI of the tunnels list API resource

Return type:

str

class ngrok.datatypes.TunnelSession(client, props)

property agent_version: str

version of the ngrok agent that started this ngrok tunnel session

Return type:

str

property credential: Ref

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

Return type:

Ref

property id: str

unique tunnel session resource identifier

Return type:

str

property ip: str

source ip address of the tunnel session

Return type:

str

property metadata: str

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

Return type:

str

property os: str

operating system of the host the ngrok agent is running on

Return type:

str

property region: str

the ngrok region identifier in which this tunnel session was started

Return type:

str

property started_at: datetime

time when the tunnel session first connected to the ngrok servers

Return type:

datetime

property transport: str

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

Return type:

str

property uri: str

URI to the API resource of the tunnel session

Return type:

str

class ngrok.datatypes.TunnelSessionList(client, props)

property next_page_uri: str

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

Return type:

str

property tunnel_sessions: Sequence[TunnelSession]

list of all tunnel sessions on this account

Return type:

Sequence[TunnelSession]

property uri: str

URI to the API resource of the tunnel session list

Return type:

str

class ngrok.datatypes.UserAgent(client, props)

property browser_name: str

browser name (e.g. Chrome)

Return type:

str

property browser_version: str

browser version (e.g. 102)

Return type:

str

property device_type: str

type of device (e.g. Desktop)

Return type:

str

property os_name: str

operating system name (e.g. MacOS)

Return type:

str

property os_version: str

operating system version (e.g. 10.15.7)

Return type:

str

property raw: str

raw User-Agent request header

Return type:

str

class ngrok.datatypes.WeightedBackend(client, props)

property backends: Mapping[str, int]

the ids of the child backends to their weights [0-10000]

Return type:

Mapping[str, int]

property created_at: datetime

timestamp when the backend was created, RFC 3339 format

Return type:

datetime

delete()

property description: str

human-readable description of this backend. Optional

Return type:

str

property id: str

unique identifier for this Weighted backend

Return type:

str

property metadata: str

arbitrary user-defined machine-readable data of this backend. Optional

Return type:

str

update(description=None, metadata=None, backends={})

property uri: str

URI of the WeightedBackend API resource

Return type:

str

class ngrok.datatypes.WeightedBackendList(client, props)

property backends: Sequence[WeightedBackend]

the list of all Weighted backends on this account

Return type:

Sequence[WeightedBackend]

property next_page_uri: str

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

Return type:

str

property uri: str

URI of the Weighted backends list API resource

Return type:

str