ngrok-api#
This is the official helper library for working with the ngrok HTTP API from Python.
Getting Started#
Installation#
pip install ngrok-api
Quickstart Example#
After you’ve installed the package, you’ll need an API key. Create one on the API Keys page of your ngrok dashboard.
In your application’s code, construct an Client
object
with the API key. API services can be accessed as properties of the client
object. That’s it!
import ngrok
# construct the api client
client = ngrok.Client("<API KEY>")
# list all online tunnels
for t in client.tunnels.list():
print(t)
# create an ip policy the allows traffic from some subnets
policy = client.ip_policies.create()
for cidr in ["24.0.0.0/8", "12.0.0.0/8"]:
client.ip_policy_rules.create(cidr=cidr, ip_policy_id=policy.id, action="allow")
Automatic Paging#
The ngrok API pages all list resources but this library abstracts that away
from you. All response objects from any list()
methods return an object that
implements an __iter__()
method which will automatically fetch additional
pages for you.
import ngrok
client = ngrok.Client("<API KEY>")
# list all ip policies, transparently fetching additional
# pages for you if necessary
for p in client.ip_policies.list():
print(p)
Instance Methods#
Instance methods like update
and delete
can be invoked on an instance of an
API object itself as well as directly without needing to first fetch the object.
- ::
import ngrok
client = ngrok.Client(“<API KEY>”)
# update the metadata of a credential cred = client.credentials.get(“cr_1kYyunEyn6XHHlqyMBLrj5nxkoz”) cred.update(metadata=json.dumps({
“server_name”: “giraffe-1”,
}))
# or do it in single call cred = client.credentials.update(“cr_1kYyunEyn6XHHlqyMBLrj5nxkoz”, metadata=json.dumps({
“server_name”: “giraffe-1”,
}))
Error Handling#
The ngrok API returns detailed information when an API call fails. Consult the section on errors for additional details.
import ngrok
client = ngrok.Client("<API KEY>")
try:
policy = client.ip_policies.create()
client.ip_policy_rules.create(cidr="24.0.0.0/8", ip_policy_id=policy.id, action="not a valid action")
except ngrok.Error as e:
print("http status code", e.http_status_code)
print("ngrok error code", e.error_code)
print("ngrok error message", e.message)
print("optional additional error-specific details", e.details)
API Reference#
- Client
Client
Client.abuse_reports
Client.agent_ingresses
Client.api_keys
Client.application_sessions
Client.application_users
Client.backends
Client.bot_users
Client.certificate_authorities
Client.credentials
Client.edge_modules
Client.edges
Client.endpoints
Client.event_destinations
Client.event_sources
Client.event_subscriptions
Client.ip_policies
Client.ip_policy_rules
Client.ip_restrictions
Client.reserved_addrs
Client.reserved_domains
Client.ssh_certificate_authorities
Client.ssh_credentials
Client.ssh_host_certificates
Client.ssh_user_certificates
Client.tls_certificates
Client.tunnel_sessions
Client.tunnels
- Datatypes
APIKey
APIKeyList
AWSAuth
AWSCredentials
AWSRole
AbuseReport
AbuseReportHostname
AgentIngress
AgentIngress.certificate_management_policy
AgentIngress.certificate_management_status
AgentIngress.created_at
AgentIngress.delete()
AgentIngress.description
AgentIngress.domain
AgentIngress.id
AgentIngress.metadata
AgentIngress.ns_targets
AgentIngress.region_domains
AgentIngress.update()
AgentIngress.uri
AgentIngressCertJob
AgentIngressCertPolicy
AgentIngressCertStatus
AgentIngressList
ApplicationSession
ApplicationSession.application_user
ApplicationSession.browser_session
ApplicationSession.created_at
ApplicationSession.delete()
ApplicationSession.edge
ApplicationSession.endpoint
ApplicationSession.expires_at
ApplicationSession.id
ApplicationSession.last_active
ApplicationSession.public_url
ApplicationSession.route
ApplicationSession.uri
ApplicationSessionList
ApplicationUser
ApplicationUserList
BotUser
BotUserList
BrowserSession
CertificateAuthority
CertificateAuthority.ca_pem
CertificateAuthority.created_at
CertificateAuthority.delete()
CertificateAuthority.description
CertificateAuthority.extended_key_usages
CertificateAuthority.id
CertificateAuthority.key_usages
CertificateAuthority.metadata
CertificateAuthority.not_after
CertificateAuthority.not_before
CertificateAuthority.subject_common_name
CertificateAuthority.update()
CertificateAuthority.uri
CertificateAuthorityList
Credential
CredentialList
Endpoint
Endpoint.bindings
Endpoint.created_at
Endpoint.delete()
Endpoint.description
Endpoint.domain
Endpoint.edge
Endpoint.host
Endpoint.hostport
Endpoint.id
Endpoint.metadata
Endpoint.name
Endpoint.port
Endpoint.principal
Endpoint.principal_id
Endpoint.proto
Endpoint.public_url
Endpoint.region
Endpoint.scheme
Endpoint.tcp_addr
Endpoint.traffic_policy
Endpoint.tunnel
Endpoint.tunnel_session
Endpoint.type
Endpoint.update()
Endpoint.updated_at
Endpoint.upstream_proto
Endpoint.upstream_url
Endpoint.uri
Endpoint.url
EndpointBackend
EndpointBackendMutate
EndpointCircuitBreaker
EndpointCompression
EndpointIPPolicy
EndpointIPPolicyMutate
EndpointList
EndpointMutualTLS
EndpointMutualTLSMutate
EndpointOAuth
EndpointOAuthAmazon
EndpointOAuthFacebook
EndpointOAuthGitHub
EndpointOAuthGitLab
EndpointOAuthGoogle
EndpointOAuthLinkedIn
EndpointOAuthMicrosoft
EndpointOAuthProvider
EndpointOAuthTwitch
EndpointOIDC
EndpointRequestHeaders
EndpointResponseHeaders
EndpointSAML
EndpointSAML.allow_idp_initiated
EndpointSAML.assertion_consumer_service_url
EndpointSAML.authorized_groups
EndpointSAML.cookie_prefix
EndpointSAML.enabled
EndpointSAML.entity_id
EndpointSAML.force_authn
EndpointSAML.idp_metadata
EndpointSAML.inactivity_timeout
EndpointSAML.maximum_duration
EndpointSAML.metadata_url
EndpointSAML.nameid_format
EndpointSAML.options_passthrough
EndpointSAML.request_signing_certificate_pem
EndpointSAML.single_logout_url
EndpointSAMLMutate
EndpointSAMLMutate.allow_idp_initiated
EndpointSAMLMutate.authorized_groups
EndpointSAMLMutate.cookie_prefix
EndpointSAMLMutate.enabled
EndpointSAMLMutate.force_authn
EndpointSAMLMutate.idp_metadata
EndpointSAMLMutate.inactivity_timeout
EndpointSAMLMutate.maximum_duration
EndpointSAMLMutate.nameid_format
EndpointSAMLMutate.options_passthrough
EndpointTLSTermination
EndpointTLSTerminationAtEdge
EndpointTrafficPolicy
EndpointUserAgentFilter
EndpointWebhookValidation
EndpointWebsocketTCPConverter
EventDestination
EventDestinationList
EventSource
EventSourceList
EventSourceReplace
EventSubscription
EventSubscriptionList
EventTarget
EventTargetAzureLogsIngestion
EventTargetCloudwatchLogs
EventTargetDatadog
EventTargetFirehose
EventTargetKinesis
FailoverBackend
FailoverBackendList
HTTPResponseBackend
HTTPResponseBackendList
HTTPSEdge
HTTPSEdgeList
HTTPSEdgeRoute
HTTPSEdgeRoute.backend
HTTPSEdgeRoute.circuit_breaker
HTTPSEdgeRoute.compression
HTTPSEdgeRoute.created_at
HTTPSEdgeRoute.delete()
HTTPSEdgeRoute.description
HTTPSEdgeRoute.edge_id
HTTPSEdgeRoute.id
HTTPSEdgeRoute.ip_restriction
HTTPSEdgeRoute.match
HTTPSEdgeRoute.match_type
HTTPSEdgeRoute.metadata
HTTPSEdgeRoute.oauth
HTTPSEdgeRoute.oidc
HTTPSEdgeRoute.request_headers
HTTPSEdgeRoute.response_headers
HTTPSEdgeRoute.saml
HTTPSEdgeRoute.traffic_policy
HTTPSEdgeRoute.update()
HTTPSEdgeRoute.uri
HTTPSEdgeRoute.user_agent_filter
HTTPSEdgeRoute.webhook_verification
HTTPSEdgeRoute.websocket_tcp_converter
IPPolicy
IPPolicyList
IPPolicyRule
IPPolicyRuleList
IPRestriction
IPRestrictionList
IdentityProvider
Location
Ref
ReservedAddr
ReservedAddrList
ReservedDomain
ReservedDomain.acme_challenge_cname_target
ReservedDomain.certificate
ReservedDomain.certificate_management_policy
ReservedDomain.certificate_management_status
ReservedDomain.cname_target
ReservedDomain.created_at
ReservedDomain.delete()
ReservedDomain.description
ReservedDomain.domain
ReservedDomain.id
ReservedDomain.metadata
ReservedDomain.region
ReservedDomain.uri
ReservedDomainCertJob
ReservedDomainCertPolicy
ReservedDomainCertStatus
ReservedDomainList
SSHCertificateAuthority
SSHCertificateAuthorityList
SSHCredential
SSHCredentialList
SSHHostCertificate
SSHHostCertificate.certificate
SSHHostCertificate.created_at
SSHHostCertificate.delete()
SSHHostCertificate.description
SSHHostCertificate.id
SSHHostCertificate.key_type
SSHHostCertificate.metadata
SSHHostCertificate.principals
SSHHostCertificate.public_key
SSHHostCertificate.ssh_certificate_authority_id
SSHHostCertificate.update()
SSHHostCertificate.uri
SSHHostCertificate.valid_after
SSHHostCertificate.valid_until
SSHHostCertificateList
SSHUserCertificate
SSHUserCertificate.certificate
SSHUserCertificate.created_at
SSHUserCertificate.critical_options
SSHUserCertificate.delete()
SSHUserCertificate.description
SSHUserCertificate.extensions
SSHUserCertificate.id
SSHUserCertificate.key_type
SSHUserCertificate.metadata
SSHUserCertificate.principals
SSHUserCertificate.public_key
SSHUserCertificate.ssh_certificate_authority_id
SSHUserCertificate.update()
SSHUserCertificate.uri
SSHUserCertificate.valid_after
SSHUserCertificate.valid_until
SSHUserCertificateList
StaticBackend
StaticBackendList
StaticBackendTLS
TCPEdge
TCPEdgeList
TLSCertificate
TLSCertificate.certificate_pem
TLSCertificate.created_at
TLSCertificate.delete()
TLSCertificate.description
TLSCertificate.extended_key_usages
TLSCertificate.id
TLSCertificate.issued_at
TLSCertificate.issuer_common_name
TLSCertificate.key_usages
TLSCertificate.metadata
TLSCertificate.not_after
TLSCertificate.not_before
TLSCertificate.private_key_type
TLSCertificate.serial_number
TLSCertificate.subject_alternative_names
TLSCertificate.subject_common_name
TLSCertificate.subject_country
TLSCertificate.subject_locality
TLSCertificate.subject_organization
TLSCertificate.subject_organizational_unit
TLSCertificate.subject_province
TLSCertificate.update()
TLSCertificate.uri
TLSCertificateList
TLSCertificateSANs
TLSEdge
TLSEdgeList
Tunnel
TunnelGroupBackend
TunnelGroupBackendList
TunnelList
TunnelSession
TunnelSessionList
UserAgent
WeightedBackend
WeightedBackendList
- Errors
- Abuse Reports
- Agent Ingresses
- API Keys
- Application Sessions
- Application Users
- Tunnel Sessions
- Failover Backends
- HTTP Response Backends
- Static Backends
- Tunnel Group Backends
- Weighted Backends
- Bot Users
- Certificate Authorities
- Tunnel Credentials
- HTTPS Edge Routes
- HTTPS Edges
- HTTPS Edge Mutual TLS Module
- HTTPS Edge TLS Termination Module
- HTTPS Edge Route Backend Module
- HTTPS Edge Route IP Restriction Module
- HTTPS Edge Route Request Headers Module
- HTTPS Edge Route Response Headers Module
- HTTPS Edge Route Compression Module
- HTTPS Edge Route Circuit Breaker Module
- HTTPS Edge Route Webhook Verification Module
- HTTPS Edge Route OAuth Module
- HTTPS Edge Route SAML Module
- HTTPS Edge Route OIDC Module
- HTTPS Edge Route Websocket TCP Converter Module
- HTTPS Edge Route User Agent Filter Module
- HTTPS Edge Route Traffic Policy Module
- TCP Edges
- TCP Edge Backend Module
- TCP Edge IP Restriction Module
- TCP Edge Traffic Policy Module
- TLS Edges
- TLS Edge Backend Module
- TLS Edge IP Restriction Module
- TLS Edge Mutual TLS Module
- TLS Edge TLS Termination Module
- TLS Edge Traffic Policy Module
- Endpoints
- Event Destinations
- Event Subscriptions
- Event Sources
- IP Policies
- IP Policy Rules
- IP Restrictions
- Reserved Addresses
- Reserved Domains
- SSH Certificate Authorities
- SSH Credentials
- SSH Host Certificates
- SSH User Certificates
- TLS Certificates
- Tunnels