Sign in
Custom Domains

Create Custom Domain

Registers a custom domain for a control plane. After creation, Konnect provisions a TLS certificate and configures SNI routing, transitioning the domain through initializing → ready. To complete setup, configure two CNAME records at your DNS registrar: one pointing your domain to the Konnect gateway hostname, and one pointing _acme-challenge.<your-domain> to the ACME challenge hostname provided by Konnect. Use the online-status endpoint to verify both records are correctly configured.

post/v2/cloud-gateways/custom-domains

Request body

control_plane_idstring uuid required

ID of the Konnect control plane. Can be retrieved from the Control Planes API or the Konnect UI.

control_plane_geo'us' | 'eu' | 'au' | 'me' | 'in' | 'sg' required

Geographic region of the control plane. Supported values:

  • us — United States
  • eu — Europe
  • au — Australia
  • me — Middle East
  • in — India
  • sg — Singapore
domainstring required

Domain name of the custom domain.

kind'dedicated.v0' | 'serverless.v1'

Pre-release Feature This feature is currently in beta and is subject to change.

Kind of the custom domain based on Cloud Gateway deployment.

Example request

{
  "control_plane_id": "0949471e-b759-45ba-87ab-ee63fb781388",
  "domain": "example.com"
}

Response

Response format for creating a custom domain for a control-plane in the global API.

idstring uuid required
control_plane_idstring uuid required

ID of the Konnect control plane. Can be retrieved from the Control Planes API or the Konnect UI.

control_plane_geo'us' | 'eu' | 'au' | 'me' | 'in' | 'sg' required

Geographic region of the control plane. Supported values:

  • us — United States
  • eu — Europe
  • au — Australia
  • me — Middle East
  • in — India
  • sg — Singapore
domainstring required

Domain name of the custom domain.

certificate_idstring uuid nullable

Certificate ID for the certificate representing this domain and stored on data-planes for this control-plane. Can be retrieved via the control-planes API for this custom domain's control-plane.

sni_idstring uuid nullable

Server Name Indication ID for this domain and stored on data-planes for this control-plane. Can be retrieved via the control-planes API for this custom domain's control-plane.

state'created' | 'initializing' | 'ready' | 'terminating' | 'terminated' | 'error' required

The current state of the custom domain. Possible values:

  • created — The domain has been registered but TLS provisioning has not yet started.
  • initializing — Konnect is provisioning the TLS certificate and configuring SNI routing.
  • ready — The domain is fully provisioned and serving traffic.
  • terminating — The domain is being deleted and its TLS certificate is being removed.
  • terminated — The domain has been fully deleted and is no longer available.
  • error — Provisioning failed; check state_metadata for details.
entity_versioninteger required

Monotonically-increasing version count of the custom domain, to indicate the order of updates to the custom domain.

created_atstring date-time required

An RFC-3339 timestamp representation of custom domain creation date.

updated_atstring date-time required

An RFC-3339 timestamp representation of custom domain update date.

kind'dedicated.v0' | 'serverless.v1'

Pre-release Feature This feature is currently in beta and is subject to change.

Kind of the custom domain based on Cloud Gateway deployment.

Example response

{
  "id": "39ed3790-085d-4605-9627-f96d86aaf425",
  "control_plane_id": "0949471e-b759-45ba-87ab-ee63fb781388",
  "domain": "example.com",
  "certificate_id": "3b7cbeee-fbec-440e-a5ef-89e7dec3b9d0",
  "sni_id": "a8f11ea8-af09-4422-9735-5d4f8910aba1",
  "state_metadata": {
    "reported_status": "INVALID",
    "reason": "CNAME points to '_acme-challenge.<prefix>.gateways.konghq.tech.' instead of '_acme-challenge.<prefix>.acme.gateways.konghq.tech.'\n"
  },
  "entity_version": 1,
  "created_at": "2022-11-04T20:10:06.927Z",
  "updated_at": "2022-11-04T20:10:06.927Z"
}

Changes

Changed in 4 of the 75 revisions of this API.1123

  • 6dabb1df19ab2See the full diff
    • ○

      added the new optional request property kind

      new-optional-request-property

    • ○

      added the optional property kind to the response with the 201 status

      response-optional-property-added

  • 8ab3ec3ed3011See the full diff
    • ●

      added the new type enum value to the allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterStandard]/rule response property for the response status 400

      response-property-enum-value-added

  • ddf026fbd25b11See the full diff
    • ●

      added the new sg enum value to the control_plane_geo response property for the response status 201

      response-property-enum-value-added

    • ○

      added the new sg enum value to the request property control_plane_geo

      request-property-enum-value-added

  • 3c0154b2053a11See the full diff
    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterChoiceItem]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterDependentItem]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterMaximumLength]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterMinimumLength]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property allOf[subschema #2]/invalid_parameters/items/oneOf[InvalidParameterStandard]/source became nullable for the status 400

      response-property-became-nullable

    • ▲

      the response property detail became nullable for the status 401

      response-property-became-nullable

    • ▲

      the response property instance became nullable for the status 401

      response-property-became-nullable

    • ▲

      the response property state_metadata/reason became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property state_metadata/reported_status became nullable for the status 201

      response-property-became-nullable

    • ▲

      the response property status became nullable for the status 401

      response-property-became-nullable

    • ▲

      the response property title became nullable for the status 401

      response-property-became-nullable

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog