Looking for the new Developer Portal beta docs? Try the beta now.

Custom Domains for Dev Portal

Konnect integrates domain name management and configuration in the Dev Portal.

Dev Portal

Every Dev Portal instance has an auto-generated default URL. You can also manage custom URLs within Konnect. This gives users the ability to access the Dev Portal from either the default URL, for example https://example.us.portal.konghq.com, or a custom URL like portal.example.com.

To add a custom URL to Dev Portal, you need:

A domain and access to configure the domain’s DNS CNAME records
Your organization’s auto-generated default Dev Portal URL
A CAA DNS record that only allows pki.goog if any pre-existing CAA DNS records are present on the domain

You can also choose to self-host the Dev Portal with Netlify or any other static hosting service that supports single page applications.

Configure DNS

In your DNS configuration, create a CNAME record for the domain you want to use using the automatically generated Dev Portal URL. The record will look like this:

Type	Name	Value
CNAME	portal	`https://example.us.portal.konghq.com`

If your domain has specific CAA DNS records that list authorized certificate authorities/issuers, you’ll also need to create a new CAA DNS record to permit Google Trust Services as an issuer. If your domain doesn’t currently have any CAA DNS records, it means all issuers are implicitly allowed, and there’s no need for a new CAA DNS record in that case.

Update Dev Portal URL settings

To add a custom URL to Dev Portal, open Dev Portal, click Settings, then follow these steps:

Open the Portal Domain tab.
Enter the fully qualified domain name (FQDN) including the subdomain, if applicable, into the Custom Hosted Domain field. Don’t include a path or protocol (e.g. https://).
Click Save Custom Domain.
Click Confirm to begin the domain verification process.

Domain name restrictions

Because of SSL certificate authority restrictions, Konnect can’t generate SSL certificates for the following domains:

TLDs containing a brand name: .aws, .microsoft, .ebay
Hosting provider subdomains: .amazonaws.com, .azurewebsites.net
TLDs restricted by US export laws:
- .af Afghanistan
- .by The Republic of Belarus
- .cu Cuba
- .er Eritrea
- .gn Guinea
- .ir Islamic Republic of Iran
- .kp Democratic People’s Republic of Korea
- .lr Liberia
- .ru The Russian Federation
- .ss South Sudan
- .su Soviet Union
- .sy Syrian Arab Republic
- .zw Zimbabwe

If you have any questions, contact Support.

Delete a custom URL

Delete a custom Dev Portal URL through your organization’s Konnect admin UI.

In Konnect, open Dev Portal, then click Settings.
Open the Portal Domain tab.
Click Delete Custom Domain

Troubleshoot DNS

After the DNS verification process is complete, Konnect will attempt to automatically generate an SSL certificate for your custom domain. This process can take several hours. If you attempt to access the custom URL from a browser before the certificate generation process is finished, you will receive an SSL certificate error. If this process takes more than 24 hours, check if the new DNS record is correctly applied. You can use the dig tool to troubleshoot your DNS:

Run dig, replacing CUSTOM_DOMAIN with your custom domain and CUSTOM_DOMAIN_DNS with the DNS server for the custom domain:
```
 dig +nocmd @CUSTOM_DOMAIN_DNS cname CUSTOM_DOMAIN +noall +answer
```
The output will look like this:
```
 portal.example.com.	172	IN	CNAME	example.us.portal.konghq.com.
```

where portal.example.com is your custom domain and example.us.portal.konghq.com is the default auto-generated URL for your Dev Portal.

Note: If the command returns no output, or the values are incorrect, check the custom domain DNS configuration or contact your DNS provider. You may need to reset your Dev Portal domain settings to fix your DNS records, you can do this by deleting the custom URL and setting the portal URL again.