Skip to main content
POST
/
reserved_domains
Create
curl --request POST \
  --url https://api.ngrok.com/reserved_domains \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'ngrok-version: <ngrok-version>' \
  --data '{
  "domain": "<string>",
  "region": "<string>",
  "description": "<string>",
  "metadata": "<string>",
  "certificate_id": "<string>",
  "certificate_management_policy": {
    "authority": "<string>",
    "private_key_type": "<string>"
  }
}'
{
  "id": "<string>",
  "uri": "<string>",
  "created_at": "<string>",
  "description": "<string>",
  "metadata": "<string>",
  "domain": "<string>",
  "region": "<string>",
  "cname_target": "<string>",
  "certificate": {
    "id": "<string>",
    "uri": "<string>"
  },
  "certificate_management_policy": {
    "authority": "<string>",
    "private_key_type": "<string>"
  },
  "certificate_management_status": {
    "renews_at": "<string>",
    "provisioning_job": {
      "error_code": "<string>",
      "msg": "<string>",
      "started_at": "<string>",
      "retries_at": "<string>"
    }
  },
  "acme_challenge_cname_target": "<string>"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
ngrok-version
integer
default:2
required

Body

application/json
​
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
object

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled. Optional, mutually exclusive with certificate_id.

Response

201 - application/json

Create a new reserved domain.

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

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
object

configuration for automatic management of TLS certificates for this domain, or null if automatic management is disabled

​
certificate_management_status
object

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.