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

Customize the Konnect Dev Portal

Konnect has built-in customization options for managing the Dev Portal so that you can build a consistent experience for the consumers of your API. Customizing your Dev Portal to reflect the likeness of your brand can help convince developers to create applications with your services. With Konnect, you can customize everything from the application. Konnect also offers pre-built themes.

Appearance

To customize Dev Portal, you have two options:

Basic customization using the Dev Portal Appearance settings in the UI
Complete customization using the open source Dev Portal client

Basic customization

The Dev Portal can be customized by those with admin roles via the Appearance settings in the Konnect admin UI. To access the appearance settings, click Dev Portal, then Appearance.

From the Appearance menu you have the ability to modify the following options:

Logos: default logo and favicon
Home Page Header: welcome message, primary header, and header image
Colors: background, text, and button colors
Themes: default theme and dark mode
Fonts

For details on the requirements for each customizable option, hover over the information (i) icon next to each item in the UI.

Complete customization using the open source Dev Portal

You can completely customize the Dev Portal using the open source Dev Portal client. To enable the self-hosted Dev Portal, navigate to Dev Portal > Settings, then set up a custom hosted domain and a custom self-hosted UI domain in the Portal Domain tab. They must share a common top-level and second-level domain for security purposes (e.g. api-developer.company.com and developer.company.com)

This self-hosted portal provides the following benefits:

Fully customizable: Use the example frontend Dev Portal application as a starting point and then customize Dev Portal for your needs using the Portal API and Portal SDK. You can also integrate the API specs with workflows tailored to your organization’s own processes.
Hosting service choice: When you self-host, you also get to choose which hosting service you use to deploy your Dev Portal.
Range of customization options: With the self-hosted Dev Portal, you determine how much you want to customize. You can choose to use the example application right out of the box, or you can use the Portal API and Portal SDK for more fine-grained control.

Custom Dev Portal URL

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 allows pki.goog only 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 →

Single sign-on

A Konnect admin can configure single sign-on (SSO) for the Dev Portal via the identity settings in the Konnect admin interface.

To configure single sign-on, open Dev Portal, click Settings, then follow these steps:

Open the Identity tab.
Copy the callback URL and enter it in your identity provider.
Enter the full domain, including the subdomain and protocol, into the Provider URL field (also known as Issuer). For example, https://accounts.google.com for Google IdP.
Enter the unique identifier provided by the IdP into the Client ID field.
Enter the secret used to verify ownership of your IdP client into the Client Secret field.

Configuration requirements

You must always have a form of authentication configured. Built-in and SSO can be used individually or in combination. Each state results in a different user experience, as represented in the following table:

State	SSO registration	SSO sign in	Built-in registration	Built-in sign in	Information
SSO: Enabled Built-in: Disabled	✅	✅	❌	❌	- Developers can register and log in with SSO. - Developers registered with built-in authentication are forced to use SSO. - The built-in authentication window does not display from the Dev Portal.
SSO: Disabled Built-in: Enabled	❌	❌	✅	✅	- Developers can register and log in with a username and password.
SSO: Enabled Built-in: Enabled	✅	✅	✅	✅	- Developers can register and log in with either form of authentication.

OIDC Details

If a user account associated with a Konnect developer is removed from the IdP, the Konnect developer account is not deleted. A Konnect admin must delete it from the Konnect dashboard.
If a Konnect developer associated with an IdP user is deleted, the same IdP user can re-authenticate with the Dev Portal and a new Konnect developer account is created. To persistently revoke access for developers authenticating through your IdP, you must remove the ability for that user to authenticate with the IdP.
User information from the IdP is not synced with Konnect developers after the first login.