Skip to main content

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 '{"domain":"myapp.mydomain.com","region":"us","certificate_id":"cert_2TMGGCjnG4ldki1rQ9JXaALQeMo"}' \
https://api.ngrok.com/reserved_domains

Parameters

   
namestringthe domain name to reserve. It may be a full domain name like app.example.com. If the name does not contain a '.' it will reserve that subdomain on ngrok.io.
domainstringhostname of the reserved domain
regionstringreserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
certificate_idstringID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with certificate_management_policy.
certificate_management_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with certificate_id.

ReservedDomainCertPolicy parameters

   
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

{
"id": "rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"uri": "https://api.ngrok.com/reserved_domains/rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"created_at": "2023-07-31T23:17:17Z",
"domain": "myapp.mydomain.com",
"region": "us",
"cname_target": "2hpegpyop.cname.us.ngrok.io",
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"certificate": {
"id": "cert_2TMGGCjnG4ldki1rQ9JXaALQeMo",
"uri": "https://api.ngrok.com/tls_certificates/cert_2TMGGCjnG4ldki1rQ9JXaALQeMo"
},
"certificate_management_policy": null,
"certificate_management_status": null,
"acme_challenge_cname_target": null
}

Fields

   
idstringunique reserved domain resource identifier
uristringURI of the reserved domain API resource
created_atstringtimestamp when the reserved domain was created, RFC 3339 format
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domainstringhostname of the reserved domain
regionstringreserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
certificateRefobject 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_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusReservedDomainCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled
acme_challenge_cname_targetstringDNS 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

   
idstringa resource identifier
uristringa uri for locating a resource

ReservedDomainCertPolicy fields

   
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.

ReservedDomainCertStatus fields

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

ReservedDomainCertJob fields

   
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 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_2TMGGEMpKpr8RdLg2fo46zIDfV1

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_2TMGGEMpKpr8RdLg2fo46zIDfV1

Response

Returns a 200 response on success

Example Response

{
"id": "rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"uri": "https://api.ngrok.com/reserved_domains/rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"created_at": "2023-07-31T23:17:17Z",
"description": "point-of-sale new york #302",
"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
"domain": "myapp.mydomain.com",
"region": "us",
"cname_target": "2hpegpyop.cname.us.ngrok.io",
"http_endpoint_configuration": {
"id": "ec_2TMGGDmptBVbFfvEmEH1AAIQkkS",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2TMGGDmptBVbFfvEmEH1AAIQkkS"
},
"https_endpoint_configuration": {
"id": "ec_2TMGGHLq3D9dJ1LiwRZ9Id1ZXzm",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2TMGGHLq3D9dJ1LiwRZ9Id1ZXzm"
},
"certificate": null,
"certificate_management_policy": {
"authority": "letsencrypt",
"private_key_type": "ecdsa"
},
"certificate_management_status": null,
"acme_challenge_cname_target": null
}

Fields

   
idstringunique reserved domain resource identifier
uristringURI of the reserved domain API resource
created_atstringtimestamp when the reserved domain was created, RFC 3339 format
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domainstringhostname of the reserved domain
regionstringreserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
certificateRefobject 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_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusReservedDomainCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled
acme_challenge_cname_targetstringDNS 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

   
idstringa resource identifier
uristringa uri for locating a resource

ReservedDomainCertPolicy fields

   
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.

ReservedDomainCertStatus fields

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

ReservedDomainCertJob fields

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

{
"reserved_domains": [
{
"id": "rd_2TMGGFijcv9x0SDZAMvSHINBH96",
"uri": "https://api.ngrok.com/reserved_domains/rd_2TMGGFijcv9x0SDZAMvSHINBH96",
"created_at": "2023-07-31T23:17:18Z",
"description": "Device 0001 Dashboard",
"metadata": "{\"service\": \"dashboard\"}",
"domain": "manage-0001.app.example.com",
"region": "us",
"cname_target": "2wsbzgakv.cname.us.ngrok.io",
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"certificate": null,
"certificate_management_policy": {
"authority": "letsencrypt",
"private_key_type": "ecdsa"
},
"certificate_management_status": {
"renews_at": null,
"provisioning_job": {
"error_code": null,
"msg": "Managed certificate provisioning in progress.",
"started_at": "2023-07-31T23:17:18Z",
"retries_at": null
}
},
"acme_challenge_cname_target": null
},
{
"id": "rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"uri": "https://api.ngrok.com/reserved_domains/rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"created_at": "2023-07-31T23:17:17Z",
"domain": "myapp.mydomain.com",
"region": "us",
"cname_target": "2hpegpyop.cname.us.ngrok.io",
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"certificate": {
"id": "cert_2TMGGCjnG4ldki1rQ9JXaALQeMo",
"uri": "https://api.ngrok.com/tls_certificates/cert_2TMGGCjnG4ldki1rQ9JXaALQeMo"
},
"certificate_management_policy": null,
"certificate_management_status": null,
"acme_challenge_cname_target": null
}
],
"uri": "https://api.ngrok.com/reserved_domains",
"next_page_uri": null
}

Fields

   
reserved_domainsReservedDomainthe list of all reserved domains on this account
uristringURI of the reserved domain list API resource
next_page_uristringURI of the next page, or null if there is no next page

ReservedDomain fields

   
idstringunique reserved domain resource identifier
uristringURI of the reserved domain API resource
created_atstringtimestamp when the reserved domain was created, RFC 3339 format
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domainstringhostname of the reserved domain
regionstringreserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
certificateRefobject 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_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusReservedDomainCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled
acme_challenge_cname_targetstringDNS 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

   
idstringa resource identifier
uristringa uri for locating a resource

ReservedDomainCertPolicy fields

   
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.

ReservedDomainCertStatus fields

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

ReservedDomainCertJob fields

   
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 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 '{"description":"point-of-sale new york #302","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}","http_endpoint_configuration_id":"ec_2TMGGDmptBVbFfvEmEH1AAIQkkS","https_endpoint_configuration_id":"ec_2TMGGHLq3D9dJ1LiwRZ9Id1ZXzm","certificate_management_policy":{"authority":"letsencrypt"}}' \
https://api.ngrok.com/reserved_domains/rd_2TMGGEMpKpr8RdLg2fo46zIDfV1

Parameters

   
idstring
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
certificate_idstringID of a user-uploaded TLS certificate to use for connections to targeting this domain. Optional, mutually exclusive with certificate_management_policy.
certificate_management_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with certificate_id.

ReservedDomainCertPolicy parameters

   
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

{
"id": "rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"uri": "https://api.ngrok.com/reserved_domains/rd_2TMGGEMpKpr8RdLg2fo46zIDfV1",
"created_at": "2023-07-31T23:17:17Z",
"description": "point-of-sale new york #302",
"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
"domain": "myapp.mydomain.com",
"region": "us",
"cname_target": "2hpegpyop.cname.us.ngrok.io",
"http_endpoint_configuration": {
"id": "ec_2TMGGDmptBVbFfvEmEH1AAIQkkS",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2TMGGDmptBVbFfvEmEH1AAIQkkS"
},
"https_endpoint_configuration": {
"id": "ec_2TMGGHLq3D9dJ1LiwRZ9Id1ZXzm",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2TMGGHLq3D9dJ1LiwRZ9Id1ZXzm"
},
"certificate": null,
"certificate_management_policy": {
"authority": "letsencrypt",
"private_key_type": "ecdsa"
},
"certificate_management_status": null,
"acme_challenge_cname_target": null
}

Fields

   
idstringunique reserved domain resource identifier
uristringURI of the reserved domain API resource
created_atstringtimestamp when the reserved domain was created, RFC 3339 format
descriptionstringhuman-readable description of what this reserved domain will be used for
metadatastringarbitrary user-defined machine-readable data of this reserved domain. Optional, max 4096 bytes.
domainstringhostname of the reserved domain
regionstringreserve the domain in this geographic ngrok datacenter. Optional, default is us. (au, eu, ap, us, jp, in, sa)
cname_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of *.ngrok.io
certificateRefobject 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_policyReservedDomainCertPolicyconfiguration for automatic management of TLS certificates for this domain, or null if automatic management is disabled
certificate_management_statusReservedDomainCertStatusstatus of the automatic certificate management for this domain, or null if automatic management is disabled
acme_challenge_cname_targetstringDNS 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

   
idstringa resource identifier
uristringa uri for locating a resource

ReservedDomainCertPolicy fields

   
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.

ReservedDomainCertStatus fields

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

ReservedDomainCertJob fields

   
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

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_2TMGGEMpKpr8RdLg2fo46zIDfV1/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_2TMGGEMpKpr8RdLg2fo46zIDfV1/certificate

Response

Returns a 204 response with no body on success