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

Parameters

NameTypeDescription
domainstringhostname of the reserved domain
regionstringdeprecated: 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)
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

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

{
"acme_challenge_cname_target": null,
"certificate": {
"id": "cert_2k5ohRXQbVjCdrrgV7UnrYJRjUg",
"uri": "https://api.ngrok.com/tls_certificates/cert_2k5ohRXQbVjCdrrgV7UnrYJRjUg"
},
"certificate_management_policy": null,
"certificate_management_status": null,
"cname_target": "2udamkamcl8pjmrff.frjtwfzow6ywjopw.local-ngrok-cname.com",
"created_at": "2024-08-02T07:15:17Z",
"domain": "myapp.mydomain.com",
"error_redirect_url": null,
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"id": "rd_2k5ohSotoaaL8tlPSDfT2PTNYjW",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2k5ohSotoaaL8tlPSDfT2PTNYjW"
}

Fields

NameTypeDescription
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
regionstringdeprecated: 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_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)
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

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

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

ReservedDomainCertStatus fields

NameTypeDescription
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

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

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_2k5ohSotoaaL8tlPSDfT2PTNYjW

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.frjtwfzow6ywjopw.local-ngrok-cname.com",
"created_at": "2024-08-02T07:15:17Z",
"description": "point-of-sale new york #302",
"domain": "myapp.mydomain.com",
"error_redirect_url": null,
"http_endpoint_configuration": {
"id": "ec_2k5ohRspbCP9HpW7H6qCzu1NQLO",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2k5ohRspbCP9HpW7H6qCzu1NQLO"
},
"https_endpoint_configuration": {
"id": "ec_2k5ohRNQiaKePV6PAl9Mi5vxgb0",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2k5ohRNQiaKePV6PAl9Mi5vxgb0"
},
"id": "rd_2k5ohSotoaaL8tlPSDfT2PTNYjW",
"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2k5ohSotoaaL8tlPSDfT2PTNYjW"
}

Fields

NameTypeDescription
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
regionstringdeprecated: 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_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)
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

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

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

ReservedDomainCertStatus fields

NameTypeDescription
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

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 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": 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-08-02T07:15:17Z"
},
"renews_at": null
},
"cname_target": "4knqktdwka2umyjjc.frjtwfzow6ywjopw.local-ngrok-cname.com",
"created_at": "2024-08-02T07:15:17Z",
"description": "Device 0001 Dashboard",
"domain": "manage-0002.app.example.com",
"error_redirect_url": null,
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"id": "rd_2k5ohWYFJsaf0W2NV5x2nDYXIbY",
"metadata": "{\"service\": \"dashboard\"}",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2k5ohWYFJsaf0W2NV5x2nDYXIbY"
},
{
"acme_challenge_cname_target": null,
"certificate": {
"id": "cert_2k5ohRXQbVjCdrrgV7UnrYJRjUg",
"uri": "https://api.ngrok.com/tls_certificates/cert_2k5ohRXQbVjCdrrgV7UnrYJRjUg"
},
"certificate_management_policy": null,
"certificate_management_status": null,
"cname_target": "2udamkamcl8pjmrff.frjtwfzow6ywjopw.local-ngrok-cname.com",
"created_at": "2024-08-02T07:15:17Z",
"domain": "myapp.mydomain.com",
"error_redirect_url": null,
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"id": "rd_2k5ohSotoaaL8tlPSDfT2PTNYjW",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2k5ohSotoaaL8tlPSDfT2PTNYjW"
}
],
"uri": "https://api.ngrok.com/reserved_domains"
}

Fields

NameTypeDescription
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

NameTypeDescription
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
regionstringdeprecated: 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_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)
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

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

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

ReservedDomainCertStatus fields

NameTypeDescription
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

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 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_2k5ohRspbCP9HpW7H6qCzu1NQLO","https_endpoint_configuration_id":"ec_2k5ohRNQiaKePV6PAl9Mi5vxgb0","metadata":"{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}"}' \
https://api.ngrok.com/reserved_domains/rd_2k5ohSotoaaL8tlPSDfT2PTNYjW

Parameters

NameTypeDescription
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

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

{
"acme_challenge_cname_target": null,
"certificate": null,
"certificate_management_policy": {
"authority": "letsencrypt",
"private_key_type": "ecdsa"
},
"certificate_management_status": null,
"cname_target": "2udamkamcl8pjmrff.frjtwfzow6ywjopw.local-ngrok-cname.com",
"created_at": "2024-08-02T07:15:17Z",
"description": "point-of-sale new york #302",
"domain": "myapp.mydomain.com",
"error_redirect_url": null,
"http_endpoint_configuration": {
"id": "ec_2k5ohRspbCP9HpW7H6qCzu1NQLO",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2k5ohRspbCP9HpW7H6qCzu1NQLO"
},
"https_endpoint_configuration": {
"id": "ec_2k5ohRNQiaKePV6PAl9Mi5vxgb0",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2k5ohRNQiaKePV6PAl9Mi5vxgb0"
},
"id": "rd_2k5ohSotoaaL8tlPSDfT2PTNYjW",
"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2k5ohSotoaaL8tlPSDfT2PTNYjW"
}

Fields

NameTypeDescription
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
regionstringdeprecated: 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_targetstringDNS CNAME target for a custom hostname, or null if the reserved domain is a subdomain of an ngrok owned domain (e.g. *.ngrok.app)
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

NameTypeDescription
idstringa resource identifier
uristringa uri for locating a resource

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

ReservedDomainCertStatus fields

NameTypeDescription
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

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

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

Response

Returns a 204 response with no body on success