Skip to content

fix: update custom domain setup guide #732

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tamalchowdhury wants to merge 3 commits into
base: main
Choose a base branch
from
Open

fix: update custom domain setup guide #732

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
066d98d
initial commit and page improvements
tamalchowdhury May 12, 2026
4f5e0f0
update the custom domain docs
tamalchowdhury May 13, 2026
8c66ee6
update minor coderabbit suggestions
tamalchowdhury May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 123 additions & 76 deletions src/content/docs/build/domains/pointing-your-domain.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
---
page_id: f0bc688b-a817-42ab-9a20-8e09cec06f37
title: Use your own custom domain
title: Use a custom domain with Kinde
description: Complete guide for setting up custom domains in Kinde including DNS configuration, verification process, SSL certificate provisioning, and integration with social authentication providers.
sidebar:
order: 1
label: Use a custom domain
tableOfContents:
maxHeadingLevel: 3
relatedArticles:
- 1dc6ae8d-b294-468c-a2ae-ceae7261decb
- b3081ca1-2aa1-45e3-a42f-5295aac49bc3
Expand All @@ -16,6 +19,9 @@ topics:
- domains
- custom-domain
- dns
- ssl
- caa-records
- social-sign-in
sdk: []
languages: []
audience: developers
Expand All @@ -29,55 +35,95 @@ keywords:
- social auth
- domain verification
- multi-level subdomains
updated: 2024-01-15
- CAA records
- ZeroSSL
- Let's Encrypt
- first-party cookie
- auth endpoint
- domain provisioning
- KINDE_ISSUER_URL
updated: 2026-05-13
featured: false
deprecated: false
ai_summary: Complete guide for setting up custom domains in Kinde including DNS configuration, verification process, SSL certificate provisioning, and integration with social authentication providers.
ai_summary: "This guide explains how to configure a custom domain for your Kinde business. It covers the full setup: adding your custom domain in the Kinde dashboard, creating CNAME DNS records with your domain provider, and monitoring the verification and SSL provisioning process. Advanced topics include configuring CAA records to authorize both ZeroSSL (sectigo.com) and Let's Encrypt for certificate issuance, adding the custom domain to social sign-in provider apps so the sign-in form reflects your brand, and handling multi-level subdomains that require additional DNS entries. Troubleshooting guidance covers common DNS formatting tips, how to confirm the custom domain appears in your application's App keys, and how to update environment variables such as KINDE_ISSUER_URL to point to the custom domain. The FAQ section addresses provisioning time (5 minutes to a few hours), the benefits of using a custom domain (seamless user experience, first-party cookies for SPAs, branding), when to keep using the Kinde domain (Management API and machine-to-machine apps), why the challenge DNS record must stay after verification for SSL renewal, and local domain support limitations."
---

By default, Kinde issues a Kinde subdomain when you first register. But for your production environment you can use your own custom domain instead of Kinde’s as your URL. For example, `account.example.com` instead of `mydomain.kinde.com`.
Use a custom domain with Kinde and add trust to your users. Follow the steps below:

There are a few reasons you may wish to do this.
### What you need

- It will give your users the impression they have never left your application to authenticate, creating a seamless user experience.
- For Single Page Applications (SPAs) it means we can securely set a first party cookie meaning authentication state persists for full-page refreshes and new tabs.
- If you also register the domain in the configuration for any social providers you are using, the social providers auth screen will be customized with your app details.

<Aside title="When to still use the Kinde domain">

Even if you use custom domains, you need to use your Kinde domain for Kinde Management API access and machine-to-machine applications.
- A [Kinde](/get-started/guides/first-things-first/) account with **Admin** access. (Sign up for free)
- A custom domain name and access to your domain control panel.

<Aside>
This is a guide for setting up a custom domain for your Kinde business. If you are setting up custom domains for your organizations, then see this guide: [Custom domain for organizations](/build/domains/organization-custom-domain/).
</Aside>

## Before you begin
## General setup

- Name your custom domain. It needs to include a subdomain for this procedure to work. Common subdomain names include `account` , `id` , or `auth`, e.g. `account.example.com`.
- Make sure your application is configured to use the exact custom domain. This includes updating the environment variables and any relevant configuration files. For example, the KINDE_ISSUER_URL needs to be updated to the custom domain.
- Ensure that the callback and logout redirect URLs in your Kinde settings are updated with the custom domain. This can be done in the Kinde dashboard under Settings > Applications > [your app] > View details.
### 1. Add your custom domain in Kinde

## Set up in Kinde
1. Go to your Kinde dashboard > **Settings > Environment > Custom domains**.
2. Select **Add custom domain**.
3. In the dialog, enter your custom domain. Be sure to include the subdomain, for example `auth.mysite.com`.
4. Select **Save**. DNS details appear.
5. Copy the CNAME records for your domain control panel. See the next step.

Note that the verification process can take anywhere from 5 minutes to a few hours, depending on who your domain provider is. See [tips for the DNS set up](/build/domains/pointing-your-domain/#tips-for-the-dns-set-up) below.
![Kinde dashboard showing custom domain DNS setup with CNAME records to copy](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/85f23299-3d46-4650-573f-a330ec290200/socialsharingimage)

1. Go to **Settings > Environment > Custom domain**.
2. Select **Add custom domain**
3. In the dialog, enter your custom domain. Be sure to include the subdomain, for example `account.example.com`.
4. Select **Save**. DNS details appear. You need to add these to your domain provider site.
### 2. Add DNS records to your domain provider

## Add CNAME DNS records
DNS settings vary from provider to provider. Here are the general steps:

1. Go to your domain provider website.
2. Create CNAME DNS records using the DNS details generated above.
2. Select your domain, and select **Update DNS configuration**.
3. Select **Add record** and enter the following:
- Record type: `CNAME`
- Name/Host: The **DNS entry** part of your domain you used in Kinde, for example `auth`
- Target/Value: The **Value** from Kinde
- TTL: Leave as default
- Routing policy: Leave as default

<Aside type="warning">
If you are using Cloudflare, you need to add a **DNS-only** record, not proxied.
</Aside>

![Cloudflare DNS record editor with proxy status set to DNS only](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/fa3ada9d-0876-440e-68e7-8254ccafb800/socialsharingimage)

4. Select **Save**.
5. Repeat the process for the other CNAME record.

**Domain provider specific instructions:**

- [Godaddy](https://au.godaddy.com/help/add-a-cname-record-19236)
- [Cloudflare](https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#create-dns-records)
- [NameCheap](https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain/)

### 3. Check verification status in Kinde

Apologies that we can’t offer instructions for all situations, as this will be different depending on your provider. But here are the setup steps for [Godaddy](https://au.godaddy.com/help/add-a-cname-record-19236), [Cloudflare](https://community.cloudflare.com/t/adding-dns-records/52718), and [NameCheap](https://www.namecheap.com/support/knowledgebase/article.aspx/9646/2237/how-to-create-a-cname-record-for-your-domain/).
Once you have created the DNS entries, Kinde will start the verification process. This can take anywhere from a few minutes to a couple of hours. You will see **Provisioning in progress** next to your custom domain:

<Aside type="warning">
![Custom domain provisioning in progress in Kinde](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/bfbfa604-01c4-4558-e993-ac0521adcc00/socialsharingimage)

Cloudflare users: DNS entries must be DNS-only, not proxied.
When it completes, the verification status will change to **Provisioned** and an SSL certificate will be provisioned.

</Aside>
![Custom domain provisioned with SSL in Kinde](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/ac49f8f6-bc18-46c2-d692-5cf770410e00/socialsharingimage)

## CAA records (if you use them)
Your domain will then be used instead of Kinde’s. You will also receive an email notification when the process is complete.

1. Go to your Kinde dashboard > select **View details** for any of your applications.
2. Select **Details**.
3. The custom domain will be listed under **App keys** section.

![Custom domain listed under App keys in application details](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/df6c1dad-e7a7-47a5-0b08-75d8c00b3600/socialsharingimage)

Your next step is to update your code to use the custom domain.

If you encounter any errors during the setup, see the troubleshooting tips below.

## Advanced setup

### CAA records

If your domain has **CAA (Certificate Authority Authorization)** records, they restrict which certificate authorities can issue SSL certificates for your domain. Kinde provisions and renews certificates using **ZeroSSL** and **Let's Encrypt**, so you must allow both in your CAA records or certificate issuance will fail.

Expand All @@ -93,81 +139,82 @@ Add CAA records that authorize both providers. For your custom domain (or the su

If you only list one CA in your CAA records, add the other. If you have no CAA records, you don't need to add any; certificate issuance will work as normal.

## Check verification status in Kinde
### Add the custom domain to social sign in

Once you have created the DNS entries, Kinde will start the verification process. This can take anywhere from a few minutes to a couple of hours. When it completes, the verification status will change to 'Provisioned' and an SSL certificate will be provisioned.

Your domain will then be used instead of Kinde’s. You will also receive an email notification when the process is complete.
When you use social connections to authenticate users, you need to add the callback URL to the provider app so that the custom domain shows on the sign-in form, instead of kinde.com.

If you encounter any errors, such as the verification taking too long, re-check the DNS records you created on your provider site, to ensure the details are correct.
![Social sign in form with custom domain](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/9247cb87-9e7a-4977-b3f5-6c8b52f64200/public)

<Aside type="warning">
If you haven't set this up, follow these instructions for the [relevant social provider](/authenticate/social-sign-in/add-social-sign-in/).

The challenge DNS record needs to remain in place after verification in order for us to renew your SSL certificate on an ongoing basis.
If you already have social auth set up, make sure you add the custom domain callback (e.g. `account.example.com/login/callback`) as an authorized redirect URI in the provider app.

</Aside>
### Using multi-level subdomains

## Update your code
If you are using a multi-level subdomain, like `multi.subdomain.example.com`, how you set up DNS records will depend on how your zones are set up.

- Update your code to use the custom domain.
The details provided in the admin console assume the domain entered is adding a single level to your DNS zone, but if you are adding more than one level you’ll need to create others.

## Add the custom domain to social sign in
So if your business is `multi.subdomain.example.com` and your zone is `example.com`, you need to create a DNS entry for `multi.subdomain`, as well as for `_acme-challenge.multi.subdomain`.

When you use social connections to authenticate users, you need to add the callback URL to the provider app so that the custom domain shows on the sign in form, instead of kinde.com.
![Multi-level subdomain DNS records](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/ee01b968-bea8-4082-7680-cde0522fbf00/public)

<img
src="https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/9247cb87-9e7a-4977-b3f5-6c8b52f64200/public"
alt=""
width="672px"
height="auto"
fetchpriority="low"
loading="lazy"
decoding="async"
/>
There are many different ways people manage multi-level domains and zones, and unfortunately we can’t cover all variations in these instructions.

If you haven't set this up, follow these instructions for the [relevant social provider](/authenticate/social-sign-in/add-social-sign-in/).
If you already have social auth set up, make sure you add the custom domain callback (e.g. `account.example.com/login/callback` as an authorized redirect URI in the provider app.
## Tips and troubleshooting

## Domains and auth end points
### Custom domain tips

Auth endpoints are available for both custom domains and your Kinde subdomain. You can get tokens from either end point, but they are not interchangeable. For example, if you get an ID and access token from `account.example.com`, it cannot be used with `mydomain.kinde.com`.
- Name your custom domain. It needs to include a subdomain for this procedure to work. Common subdomain names include `account`, `id`, or `auth`, e.g. `account.example.com`.
- Make sure your application is configured to use the exact custom domain. This includes updating the environment variables and any relevant configuration files. For example, the `KINDE_ISSUER_URL` needs to be updated to the custom domain.
- Ensure that the callback and logout redirect URLs in your Kinde settings are updated with the custom domain. This can be done in the Kinde dashboard under **Settings > Applications > [your app] > View details**.

## Local domain
### Domains and auth endpoints

Currently, Kinde only supports `*.localhost` for non-https traffic.
Auth endpoints are available for both custom domains and your Kinde subdomain. You can get tokens from either endpoint, but they are not interchangeable. For example, if you get an ID and access token from `account.example.com`, it cannot be used with `mydomain.kinde.com`.

## Tips for the DNS set up
### Tips for the DNS set up

When you create the DNS records for linking your own domain to Kinde, be sure to match the format you have used above.

For example, if your custom domain is `account.example.com`, then:

Host = `account`
- **Host**: `account`
- **Record type**: `CNAME`
- **Value**: "Value from Kinde" (e.g., `au.kinde.com.`)
- **TTL**: Leave as default
Comment thread
coderabbitai[bot] marked this conversation as resolved.
- **Routing policy**: Leave as default

Record type = `CNAME`
## Custom domain FAQs

Value = `account.example.com`
### How long does it take to make the custom domain live?

TTL = Leave as default
The verification process can take anywhere from 5 minutes to a few hours, depending on who your domain provider is. If it's taking longer than expected, check your DNS records are correct on your provider site.

Routing policy = Leave as default
### Why use a custom domain?

## Using multi-level subdomains
Using a custom domain on Kinde gives your users a seamless experience, improves branding, and helps with security.

If you are using a multi-level subdomain, like `multi.subdomain.example.com`, how you set up DNS records will depend on how your zones are set up.
By default, Kinde issues a Kinde subdomain when you first register. But for your production environment you can use your own custom domain instead of Kinde’s as your URL. For example, `auth.mysite.com` instead of `mysite.kinde.com`.

The details provided in the admin console assumes the domain entered is adding a single level to your DNS zone, but if you are adding more than one level you’ll need to create others.
Here's why you might want to use a custom domain:

So if your business is `multi.subdomain.example.com` and your zone is `example.com`, you need to create a DNS entry for `multi.subdomain`, as well as for `_acme-challenge.multi.subdomain`.
- **Seamless experience**: It will give your users the impression they have never left your application to authenticate, creating a seamless user experience.
- **Security**: For Single Page Applications (SPAs), it means we can securely set a first-party cookie, so authentication state persists across full-page refreshes and new tabs.
- **Branding**: If you also register the domain in the configuration for any social providers you are using, the social providers auth screen will be customized with your app details.

<img
src="https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/ee01b968-bea8-4082-7680-cde0522fbf00/public"
alt=""
width="672px"
height="auto"
fetchpriority="low"
loading="lazy"
decoding="async"
/>
### When to still use the Kinde domain

There are many different ways people manage multi-level domains and zones, and unfortunately we can’t cover all variations in these instructions.
Even if you use custom domains, you need to use your Kinde domain for Kinde Management API access and machine-to-machine applications.

### Do I need to keep the challenge DNS record after verification?

Yes, the challenge DNS record needs to remain in place after verification in order for us to renew your SSL certificate on an ongoing basis.

### Does Kinde support local domains?

Currently, Kinde only supports `*.localhost` for non-https traffic.

## Get support

If you need help, contact [Kinde support](https://kinde.com/support).
Loading