Skip to main content

Agent Ingresses

Create Agent Ingress

Create a new Agent Ingress. The ngrok agent can be configured to connect to ngrok via the new set of addresses on the returned Agent Ingress.

Request

POST /agent_ingresses

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"acme devices","domain":"connect.acme.com"}' \
https://api.ngrok.com/agent_ingresses

Parameters

NameTypeDescription
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domainstringthe domain that you own to be used as the base domain name to generate regional agent ingress domains.
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional.

AgentIngressCertPolicy parameters

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 201 response on success

Example Response

{
"certificate_management_policy": null,
"certificate_management_status": null,
"created_at": "2024-02-16T19:35:32Z",
"description": "acme devices",
"domain": "connect.acme.com",
"id": "agin_2cSjz4KiqBvr9dEDroJe1IFLyDb",
"ns_targets": [
"1.kube-dns.kube-system.svc.cluster.local.",
"2.kube-dns.kube-system.svc.cluster.local.",
"3.kube-dns.kube-system.svc.cluster.local.",
"4.kube-dns.kube-system.svc.cluster.local."
],
"region_domains": ["tunnel.us.connect.acme.com"],
"uri": "/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb"
}

Fields

NameTypeDescription
idstringunique Agent Ingress resource identifier
uristringURI to the API resource of this Agent ingress
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domainstringthe domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targetsList<string>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
region_domainsList<string>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
created_atstringtimestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusAgentIngressCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

NameTypeDescription
renews_atstringtimestamp when the next renewal will be requested, RFC 3339 format
provisioning_jobAgentIngressCertJobstatus of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

NameTypeDescription
error_codestringif 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).
msgstringa message describing the current status or error
started_atstringtimestamp when the provisioning job started, RFC 3339 format
retries_atstringtimestamp when the provisioning job will be retried

Delete Agent Ingress

Delete an Agent Ingress by ID

Request

DELETE /agent_ingresses/{id}

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb

Response

Returns a 204 response with no body on success

Get Agent Ingress

Get the details of an Agent Ingress by ID.

Request

GET /agent_ingresses/{id}

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb

Response

Returns a 200 response on success

Example Response

{
"certificate_management_policy": null,
"certificate_management_status": null,
"created_at": "2024-02-16T19:35:32Z",
"description": "ACME Co. Device Ingress",
"domain": "connect.acme.com",
"id": "agin_2cSjz4KiqBvr9dEDroJe1IFLyDb",
"metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
"ns_targets": [
"1.kube-dns.kube-system.svc.cluster.local.",
"2.kube-dns.kube-system.svc.cluster.local.",
"3.kube-dns.kube-system.svc.cluster.local.",
"4.kube-dns.kube-system.svc.cluster.local."
],
"region_domains": ["tunnel.us.connect.acme.com"],
"uri": "/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb"
}

Fields

NameTypeDescription
idstringunique Agent Ingress resource identifier
uristringURI to the API resource of this Agent ingress
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domainstringthe domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targetsList<string>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
region_domainsList<string>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
created_atstringtimestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusAgentIngressCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

NameTypeDescription
renews_atstringtimestamp when the next renewal will be requested, RFC 3339 format
provisioning_jobAgentIngressCertJobstatus of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

NameTypeDescription
error_codestringif 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).
msgstringa message describing the current status or error
started_atstringtimestamp when the provisioning job started, RFC 3339 format
retries_atstringtimestamp when the provisioning job will be retried

List Agent Ingresses

List all Agent Ingresses owned by this account

Request

GET /agent_ingresses

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/agent_ingresses

Response

Returns a 200 response on success

Example Response

{
"ingresses": [
{
"certificate_management_policy": null,
"certificate_management_status": null,
"created_at": "2024-02-16T19:35:32Z",
"description": "acme devices",
"domain": "connect.acme.com",
"id": "agin_2cSjz4KiqBvr9dEDroJe1IFLyDb",
"ns_targets": [
"1.kube-dns.kube-system.svc.cluster.local.",
"2.kube-dns.kube-system.svc.cluster.local.",
"3.kube-dns.kube-system.svc.cluster.local.",
"4.kube-dns.kube-system.svc.cluster.local."
],
"region_domains": ["tunnel.us.connect.acme.com"],
"uri": "/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb"
}
],
"next_page_uri": null,
"uri": "https://api.ngrok.com/agent_ingresses"
}

Fields

NameTypeDescription
ingressesAgentIngressthe list of Agent Ingresses owned by this account
uristringURI of the Agent Ingress list API resource
next_page_uristringURI of the next page, or null if there is no next page

AgentIngress fields

NameTypeDescription
idstringunique Agent Ingress resource identifier
uristringURI to the API resource of this Agent ingress
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domainstringthe domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targetsList<string>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
region_domainsList<string>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
created_atstringtimestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusAgentIngressCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

NameTypeDescription
renews_atstringtimestamp when the next renewal will be requested, RFC 3339 format
provisioning_jobAgentIngressCertJobstatus of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

NameTypeDescription
error_codestringif 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).
msgstringa message describing the current status or error
started_atstringtimestamp when the provisioning job started, RFC 3339 format
retries_atstringtimestamp when the provisioning job will be retried

Update Agent Ingress

Update attributes of an Agent Ingress by ID.

Request

PATCH /agent_ingresses/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"description":"ACME Co. Device Ingress","metadata":"{\"device_sku\": \"824JS4RZ1F8X\"}"}' \
https://api.ngrok.com/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb

Parameters

NameTypeDescription
idstring
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional.

AgentIngressCertPolicy parameters

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 200 response on success

Example Response

{
"certificate_management_policy": null,
"certificate_management_status": null,
"created_at": "2024-02-16T19:35:32Z",
"description": "ACME Co. Device Ingress",
"domain": "connect.acme.com",
"id": "agin_2cSjz4KiqBvr9dEDroJe1IFLyDb",
"metadata": "{\"device_sku\": \"824JS4RZ1F8X\"}",
"ns_targets": [
"1.kube-dns.kube-system.svc.cluster.local.",
"2.kube-dns.kube-system.svc.cluster.local.",
"3.kube-dns.kube-system.svc.cluster.local.",
"4.kube-dns.kube-system.svc.cluster.local."
],
"region_domains": ["tunnel.us.connect.acme.com"],
"uri": "/agent_ingresses/agin_2cSjz4KiqBvr9dEDroJe1IFLyDb"
}

Fields

NameTypeDescription
idstringunique Agent Ingress resource identifier
uristringURI to the API resource of this Agent ingress
descriptionstringhuman-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadatastringarbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domainstringthe domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targetsList<string>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
region_domainsList<string>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
created_atstringtimestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policyAgentIngressCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusAgentIngressCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

NameTypeDescription
authoritystringcertificate authority to request certificates from. The only supported value is letsencrypt.
private_key_typestringtype of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

NameTypeDescription
renews_atstringtimestamp when the next renewal will be requested, RFC 3339 format
provisioning_jobAgentIngressCertJobstatus of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

NameTypeDescription
error_codestringif 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).
msgstringa message describing the current status or error
started_atstringtimestamp when the provisioning job started, RFC 3339 format
retries_atstringtimestamp when the provisioning job will be retried