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

name	string	the 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.
domain	string	hostname of the reserved domain
region	string	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (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

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

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

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	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (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 *.ngrok.io
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

id	string	a resource identifier
uri	string	a uri for locating a resource

ReservedDomainCertPolicy fields

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

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

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

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	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (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 *.ngrok.io
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

id	string	a resource identifier
uri	string	a uri for locating a resource

ReservedDomainCertPolicy fields

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

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

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

{
    "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_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

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	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (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 *.ngrok.io
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

id	string	a resource identifier
uri	string	a uri for locating a resource

ReservedDomainCertPolicy fields

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

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

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 '{"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

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

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

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

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	reserve the domain in this geographic ngrok datacenter. Optional, default is us. (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 *.ngrok.io
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

id	string	a resource identifier
uri	string	a uri for locating a resource

ReservedDomainCertPolicy fields

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

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

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