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_2fKmZrQPzxR3xN7e7t8erD2eAEh","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_2fKmZrQPzxR3xN7e7t8erD2eAEh",
"uri": "https://api.ngrok.com/tls_certificates/cert_2fKmZrQPzxR3xN7e7t8erD2eAEh"
},
"certificate_management_policy": null,
"certificate_management_status": null,
"cname_target": "2udamkamcl8pjmrff.4zq5ahiex4ieiftdz.local-ngrok-cname.com",
"created_at": "2024-04-19T20:23:21Z",
"domain": "myapp.mydomain.com",
"http_endpoint_configuration": null,
"https_endpoint_configuration": null,
"id": "rd_2fKmZr70gvQ0c4aMENN566IrCLi",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2fKmZr70gvQ0c4aMENN566IrCLi"
}
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_2fKmZr70gvQ0c4aMENN566IrCLi
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_2fKmZr70gvQ0c4aMENN566IrCLi
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.4zq5ahiex4ieiftdz.local-ngrok-cname.com",
"created_at": "2024-04-19T20:23:21Z",
"description": "point-of-sale new york #302",
"domain": "myapp.mydomain.com",
"http_endpoint_configuration": {
"id": "ec_2fKmZqoNAFgOsaqfnu8S9FNbAiz",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2fKmZqoNAFgOsaqfnu8S9FNbAiz"
},
"https_endpoint_configuration": {
"id": "ec_2fKmZlcdumbGsMrXdEj6ua4M05O",
"uri": "https://api.ngrok.com/endpoint_configurations/ec_2fKmZlcdumbGsMrXdEj6ua4M05O"
},
"id": "rd_2fKmZr70gvQ0c4aMENN566IrCLi",
"metadata": "{env: \"staging\", \"connector_id\":\"64698fcc-5f5c-4b63-910e-8669d04bd943\"}",
"region": "",
"uri": "https://api.ngrok.com/reserved_domains/rd_2fKmZr70gvQ0c4aMENN566IrCLi"
}
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. |