Reserved Domains

Create Reserved Domain

Create a new reserved domain.

Request

POST /reserved_domains

Example Request

curl \
-X POST \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"certificate_id":"cert_2gsqJSUdaNHhZLkyG7ZxW38lbNq","domain":"myapp.mydomain.com","region":"us"}' \
https://api.ngrok.com/reserved_domains

Parameters

Name	Type	Description
`domain`	string	hostname of the reserved domain
`region`	string	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)
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`certificate_id`	string	ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.

ReservedDomainCertPolicy 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

{
	"acme_challenge_cname_target": null,
	"certificate": {
		"id": "cert_2gsqJSUdaNHhZLkyG7ZxW38lbNq",
		"uri": "https://api.ngrok.com/tls_certificates/cert_2gsqJSUdaNHhZLkyG7ZxW38lbNq"
	},
	"certificate_management_policy": null,
	"certificate_management_status": null,
	"cname_target": "2udamkamcl8pjmrff.5j6jx46cugxi6fgcv.local-ngrok-cname.com",
	"created_at": "2024-05-23T20:36:00Z",
	"domain": "myapp.mydomain.com",
	"http_endpoint_configuration": null,
	"https_endpoint_configuration": null,
	"id": "rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax",
	"region": "",
	"uri": "https://api.ngrok.com/reserved_domains/rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax"
}

Fields

Name	Type	Description
`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	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)
`cname_target`	string	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)
`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.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	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.

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

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

ReservedDomainCertStatus fields

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

ReservedDomainCertJob 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 Reserved Domain

Delete a reserved domain.

Request

DELETE /reserved_domains/{id}

Example Request

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

Response

Returns a 204 response with no body on success

Get Reserved Domain

Get the details of a reserved domain.

Request

GET /reserved_domains/{id}

Example Request

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

Response

Returns a 200 response on success

Example Response

{
	"acme_challenge_cname_target": null,
	"certificate": null,
	"certificate_management_policy": {
		"authority": "letsencrypt",
		"private_key_type": "ecdsa"
	},
	"certificate_management_status": null,
	"cname_target": "2udamkamcl8pjmrff.5j6jx46cugxi6fgcv.local-ngrok-cname.com",
	"created_at": "2024-05-23T20:36:00Z",
	"description": "point-of-sale new york #302",
	"domain": "myapp.mydomain.com",
	"http_endpoint_configuration": {
		"id": "ec_2gsqJSzyIx5bx2OpqeQ6JgAbUas",
		"uri": "https://api.ngrok.com/endpoint_configurations/ec_2gsqJSzyIx5bx2OpqeQ6JgAbUas"
	},
	"https_endpoint_configuration": {
		"id": "ec_2gsqJT0hndIjEdkGLlBB4DyD9ls",
		"uri": "https://api.ngrok.com/endpoint_configurations/ec_2gsqJT0hndIjEdkGLlBB4DyD9ls"
	},
	"id": "rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax",
	"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
	"region": "",
	"uri": "https://api.ngrok.com/reserved_domains/rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax"
}

Fields

Name	Type	Description
`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	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)
`cname_target`	string	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)
`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.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	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.

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

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

ReservedDomainCertStatus fields

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

ReservedDomainCertJob 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 Reserved Domains

List all reserved domains on this account.

Request

GET /reserved_domains

Example Request

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

Response

Returns a 200 response on success

Example Response

{
	"next_page_uri": null,
	"reserved_domains": [
		{
			"acme_challenge_cname_target": null,
			"certificate": {
				"id": "cert_2gsqJSUdaNHhZLkyG7ZxW38lbNq",
				"uri": "https://api.ngrok.com/tls_certificates/cert_2gsqJSUdaNHhZLkyG7ZxW38lbNq"
			},
			"certificate_management_policy": null,
			"certificate_management_status": null,
			"cname_target": "2udamkamcl8pjmrff.5j6jx46cugxi6fgcv.local-ngrok-cname.com",
			"created_at": "2024-05-23T20:36:00Z",
			"domain": "myapp.mydomain.com",
			"http_endpoint_configuration": null,
			"https_endpoint_configuration": null,
			"id": "rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax",
			"region": "",
			"uri": "https://api.ngrok.com/reserved_domains/rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax"
		},
		{
			"acme_challenge_cname_target": null,
			"certificate": null,
			"certificate_management_policy": {
				"authority": "letsencrypt",
				"private_key_type": "ecdsa"
			},
			"certificate_management_status": {
				"provisioning_job": {
					"error_code": null,
					"msg": "Managed certificate provisioning in progress.",
					"retries_at": null,
					"started_at": "2024-05-23T20:36:00Z"
				},
				"renews_at": null
			},
			"cname_target": "4knqktdwka2umyjjc.5j6jx46cugxi6fgcv.local-ngrok-cname.com",
			"created_at": "2024-05-23T20:36:00Z",
			"description": "Device 0001 Dashboard",
			"domain": "manage-0002.app.example.com",
			"http_endpoint_configuration": null,
			"https_endpoint_configuration": null,
			"id": "rd_2gsqJPddVF904CVeAy11ukA1Crs",
			"metadata": "{\"service\": \"dashboard\"}",
			"region": "",
			"uri": "https://api.ngrok.com/reserved_domains/rd_2gsqJPddVF904CVeAy11ukA1Crs"
		}
	],
	"uri": "https://api.ngrok.com/reserved_domains"
}

Fields

Name	Type	Description
`reserved_domains`	ReservedDomain	the list of all reserved domains on this account
`uri`	string	URI of the reserved domain list API resource
`next_page_uri`	string	URI of the next page, or null if there is no next page

ReservedDomain fields

Name	Type	Description
`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	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)
`cname_target`	string	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)
`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.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	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.

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

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

ReservedDomainCertStatus fields

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

ReservedDomainCertJob 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 Reserved Domain

Update the attributes of a reserved domain.

Request

PATCH /reserved_domains/{id}

Example Request

curl \
-X PATCH \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"certificate_management_policy":{"authority":"letsencrypt"},"description":"point-of-sale new york #302","http_endpoint_configuration_id":"ec_2gsqJSzyIx5bx2OpqeQ6JgAbUas","https_endpoint_configuration_id":"ec_2gsqJT0hndIjEdkGLlBB4DyD9ls","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}"}' \
https://api.ngrok.com/reserved_domains/rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax

Parameters

Name	Type	Description
`id`	string
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`certificate_id`	string	ID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with `certificate_management_policy`.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with `certificate_id`.

ReservedDomainCertPolicy 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

{
	"acme_challenge_cname_target": null,
	"certificate": null,
	"certificate_management_policy": {
		"authority": "letsencrypt",
		"private_key_type": "ecdsa"
	},
	"certificate_management_status": null,
	"cname_target": "2udamkamcl8pjmrff.5j6jx46cugxi6fgcv.local-ngrok-cname.com",
	"created_at": "2024-05-23T20:36:00Z",
	"description": "point-of-sale new york #302",
	"domain": "myapp.mydomain.com",
	"http_endpoint_configuration": {
		"id": "ec_2gsqJSzyIx5bx2OpqeQ6JgAbUas",
		"uri": "https://api.ngrok.com/endpoint_configurations/ec_2gsqJSzyIx5bx2OpqeQ6JgAbUas"
	},
	"https_endpoint_configuration": {
		"id": "ec_2gsqJT0hndIjEdkGLlBB4DyD9ls",
		"uri": "https://api.ngrok.com/endpoint_configurations/ec_2gsqJT0hndIjEdkGLlBB4DyD9ls"
	},
	"id": "rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax",
	"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
	"region": "",
	"uri": "https://api.ngrok.com/reserved_domains/rd_2gsqJVTntVxwjtkrg1Vv3VPZ3ax"
}

Fields

Name	Type	Description
`id`	string	unique reserved domain resource identifier
`uri`	string	URI of the reserved domain API resource
`created_at`	string	timestamp when the reserved domain was created, RFC 3339 format
`description`	string	human-readable description of what this reserved domain will be used for
`metadata`	string	arbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
`domain`	string	hostname of the reserved domain
`region`	string	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)
`cname_target`	string	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)
`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.
`certificate_management_policy`	ReservedDomainCertPolicy	configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
`certificate_management_status`	ReservedDomainCertStatus	status of the automatic certificate management for this domain, or null if automatic management is disabled
`acme_challenge_cname_target`	string	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.

Ref fields

Name	Type	Description
`id`	string	a resource identifier
`uri`	string	a uri for locating a resource

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

ReservedDomainCertStatus fields

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

ReservedDomainCertJob 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

Detach Certificate Management Policy from Reserved Domain

Detach the certificate management policy attached to a reserved domain.

Request

DELETE /reserved_domains/{id}/certificate_management_policy

Example Request

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

Response

Returns a 204 response with no body on success

Detach Certificate from Reserved Domain

Detach the certificate attached to a reserved domain.

Request

DELETE /reserved_domains/{id}/certificate

Example Request

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

Response

Returns a 204 response with no body on success

Reserved Domains

Create Reserved Domain​

Request​

Example Request​

Parameters​

ReservedDomainCertPolicy parameters​

Response​

Example Response​

Fields​

Ref fields​

ReservedDomainCertPolicy fields​

ReservedDomainCertStatus fields​

ReservedDomainCertJob fields​

Delete Reserved Domain​

Request​

Example Request​

Response​

Get Reserved Domain​

Request​

Example Request​

Response​

Example Response​

Fields​

Ref fields​

ReservedDomainCertPolicy fields​

ReservedDomainCertStatus fields​

ReservedDomainCertJob fields​

List Reserved Domains​

Request​

Example Request​

Response​

Example Response​

Fields​

ReservedDomain fields​

Ref fields​

ReservedDomainCertPolicy fields​

ReservedDomainCertStatus fields​

ReservedDomainCertJob fields​

Update Reserved Domain​

Request​

Example Request​

Parameters​

ReservedDomainCertPolicy parameters​

Response​

Example Response​

Fields​

Ref fields​

ReservedDomainCertPolicy fields​

ReservedDomainCertStatus fields​

ReservedDomainCertJob fields​

Detach Certificate Management Policy from Reserved Domain​

Request​

Example Request​

Response​

Detach Certificate from Reserved Domain​

Request​

Example Request​

Response​

Create Reserved Domain

Request

Example Request

Parameters

ReservedDomainCertPolicy parameters

Response

Example Response

Fields

Ref fields

ReservedDomainCertPolicy fields

ReservedDomainCertStatus fields

ReservedDomainCertJob fields

Delete Reserved Domain

Request

Example Request

Response

Get Reserved Domain

Request

Example Request

Response

Example Response

Fields

Ref fields

ReservedDomainCertPolicy fields

ReservedDomainCertStatus fields

ReservedDomainCertJob fields

List Reserved Domains

Request

Example Request

Response

Example Response

Fields

ReservedDomain fields

Ref fields

ReservedDomainCertPolicy fields

ReservedDomainCertStatus fields

ReservedDomainCertJob fields

Update Reserved Domain

Request

Example Request

Parameters

ReservedDomainCertPolicy parameters

Response

Example Response

Fields

Ref fields

ReservedDomainCertPolicy fields

ReservedDomainCertStatus fields

ReservedDomainCertJob fields

Detach Certificate Management Policy from Reserved Domain

Request

Example Request

Response

Detach Certificate from Reserved Domain

Request

Example Request

Response