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

Name	Type	Description
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domain	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional.

AgentIngressCertPolicy parameters

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 201 response on success

Example Response

{
	"certificate_management_policy": null,
	"certificate_management_status": null,
	"created_at": "2024-08-02T07:15:39Z",
	"description": "acme devices",
	"domain": "connect.acme.com",
	"id": "agin_2k5okIo7afS6bKA3xNDLRZ9rjqk",
	"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_2k5okIo7afS6bKA3xNDLRZ9rjqk"
}

Fields

Name	Type	Description
id	string	unique Agent Ingress resource identifier
uri	string	URI to the API resource of this Agent ingress
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domain	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targets	List<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_domains	List<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_at	string	timestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status	AgentIngressCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

Name	Type	Description
renews_at	string	timestamp when the next renewal will be requested, RFC 3339 format
provisioning_job	AgentIngressCertJob	status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

Name	Type	Description
error_code	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg	string	a message describing the current status or error
started_at	string	timestamp when the provisioning job started, RFC 3339 format
retries_at	string	timestamp when the provisioning job will be retried

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_2k5okIo7afS6bKA3xNDLRZ9rjqk

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_2k5okIo7afS6bKA3xNDLRZ9rjqk

Response

Returns a 200 response on success

Example Response

{
	"certificate_management_policy": null,
	"certificate_management_status": null,
	"created_at": "2024-08-02T07:15:39Z",
	"description": "ACME Co. Device Ingress",
	"domain": "connect.acme.com",
	"id": "agin_2k5okIo7afS6bKA3xNDLRZ9rjqk",
	"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_2k5okIo7afS6bKA3xNDLRZ9rjqk"
}

Fields

Name	Type	Description
id	string	unique Agent Ingress resource identifier
uri	string	URI to the API resource of this Agent ingress
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domain	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targets	List<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_domains	List<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_at	string	timestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status	AgentIngressCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

Name	Type	Description
renews_at	string	timestamp when the next renewal will be requested, RFC 3339 format
provisioning_job	AgentIngressCertJob	status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

Name	Type	Description
error_code	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg	string	a message describing the current status or error
started_at	string	timestamp when the provisioning job started, RFC 3339 format
retries_at	string	timestamp when the provisioning job will be retried

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-08-02T07:15:39Z",
			"description": "acme devices",
			"domain": "connect.acme.com",
			"id": "agin_2k5okIo7afS6bKA3xNDLRZ9rjqk",
			"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_2k5okIo7afS6bKA3xNDLRZ9rjqk"
		}
	],
	"next_page_uri": null,
	"uri": "https://api.ngrok.com/agent_ingresses"
}

Fields

Name	Type	Description
ingresses	AgentIngress	the list of Agent Ingresses owned by this account
uri	string	URI of the Agent Ingress list API resource
next_page_uri	string	URI of the next page, or null if there is no next page

AgentIngress fields

Name	Type	Description
id	string	unique Agent Ingress resource identifier
uri	string	URI to the API resource of this Agent ingress
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domain	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targets	List<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_domains	List<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_at	string	timestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status	AgentIngressCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

Name	Type	Description
renews_at	string	timestamp when the next renewal will be requested, RFC 3339 format
provisioning_job	AgentIngressCertJob	status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

Name	Type	Description
error_code	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg	string	a message describing the current status or error
started_at	string	timestamp when the provisioning job started, RFC 3339 format
retries_at	string	timestamp when the provisioning job will be retried

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_2k5okIo7afS6bKA3xNDLRZ9rjqk

Parameters

Name	Type	Description
id	string
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional.

AgentIngressCertPolicy parameters

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

Response

Returns a 200 response on success

Example Response

{
	"certificate_management_policy": null,
	"certificate_management_status": null,
	"created_at": "2024-08-02T07:15:39Z",
	"description": "ACME Co. Device Ingress",
	"domain": "connect.acme.com",
	"id": "agin_2k5okIo7afS6bKA3xNDLRZ9rjqk",
	"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_2k5okIo7afS6bKA3xNDLRZ9rjqk"
}

Fields

Name	Type	Description
id	string	unique Agent Ingress resource identifier
uri	string	URI to the API resource of this Agent ingress
description	string	human-readable description of the use of this Agent Ingress. optional, max 255 bytes.
metadata	string	arbitrary user-defined machine-readable data of this Agent Ingress. optional, max 4096 bytes
domain	string	the domain that you own to be used as the base domain name to generate regional agent ingress domains.
ns_targets	List<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_domains	List<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_at	string	timestamp when the Agent Ingress was created, RFC 3339 format
certificate_management_policy	AgentIngressCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_status	AgentIngressCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled

AgentIngressCertPolicy fields

Name	Type	Description
authority	string	certificate authority to request certificates from. The only supported value is letsencrypt.
private_key_type	string	type of private key to use when requesting certificates. Defaults to rsa, can be either rsa or ecdsa.

AgentIngressCertStatus fields

Name	Type	Description
renews_at	string	timestamp when the next renewal will be requested, RFC 3339 format
provisioning_job	AgentIngressCertJob	status of the certificate provisioning job, or null if the certificiate isn't being provisioned or renewed

AgentIngressCertJob fields

Name	Type	Description
error_code	string	if present, an error code indicating why provisioning is failing. It may be either a temporary condition (INTERNAL_ERROR), or a permanent one the user must correct (DNS_ERROR).
msg	string	a message describing the current status or error
started_at	string	timestamp when the provisioning job started, RFC 3339 format
retries_at	string	timestamp when the provisioning job will be retried