> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Attach your own custom domain names to route production traffic to your Unkey deployments. Configure DNS records and TLS certificates.

<Info>
  Unkey Deploy is in public beta. To try it, open the product switcher in the
  top-left of the dashboard and select **Deploy**. During beta, deployed
  resources are free. We're eager for feedback, so let us know what you think
  on [Discord](https://unkey.com/discord), [X](https://x.com/unkeydev), or
  email [support@unkey.com](mailto:support@unkey.com).
</Info>

Custom domains let you serve your app from your own domain name (for example, `api.acme.com`) instead of a `*.unkey.app` subdomain. Unkey handles TLS certificate provisioning and renewal automatically.

## Add a custom domain

<Steps>
  <Step title="Open domain settings">
    Navigate to your project in the dashboard and click **Settings**. Scroll to the **Custom domains** section.
  </Step>

  <Step title="Enter your domain">
    Select the environment and enter the fully qualified domain name you want to use (for example, `api.acme.com`).

    <Frame>
      <img src="https://mintcdn.com/unkey/x4OlsjqEyio8akfR/networking/custom-domain-add.png?fit=max&auto=format&n=x4OlsjqEyio8akfR&q=85&s=9d1006945e9be8d082f7ce56e0bd23c0" alt="Custom domains settings showing environment and domain input" width="1784" height="420" data-path="networking/custom-domain-add.png" />
    </Frame>
  </Step>

  <Step title="Configure DNS records">
    After you add a domain, Unkey checks whether your DNS provider supports automatic setup. If it does, you can configure your DNS records with one click. Otherwise, you add the records manually.

    <Tabs>
      <Tab title="Automatic setup">
        If your DNS provider supports the [Domain Connect](https://www.domainconnect.org/) protocol, an **Automatic setup available** card appears with your provider's name. Click **Connect** to open your DNS provider's consent page, approve the changes, and the required DNS records are created for you automatically.

        After you approve, Unkey begins verification immediately. No manual DNS configuration is needed.

        The following providers are supported for automatic setup:

        * Cloudflare
        * Vercel DNS

        <Note>
          Automatic setup works for subdomains out of the box. For apex (root) domains, some providers like Cloudflare (via CNAME flattening) and Vercel (via ALIAS records through Domain Connect) also support automatic setup. If your provider does not support these features, configure DNS manually instead.
        </Note>
      </Tab>

      <Tab title="Manual setup">
        If automatic setup is not available, Unkey generates DNS records for you to add at your DNS provider:

        <Frame>
          <img src="https://mintcdn.com/unkey/x4OlsjqEyio8akfR/networking/custom-domain-verify.png?fit=max&auto=format&n=x4OlsjqEyio8akfR&q=85&s=6b62406a715f2c770a2e3d8ce8d0f995" alt="DNS records to add for domain verification showing TXT and CNAME entries" width="1794" height="740" data-path="networking/custom-domain-verify.png" />
        </Frame>

        A **TXT** record proves ownership of the domain. A **CNAME** record routes traffic to your deployment. Each domain receives a unique CNAME target.

        Add both records at your DNS provider. Unkey checks for them automatically and verifies within minutes once the records propagate.
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Warning>
  Both DNS records must be verified within 24 hours. If verification doesn't complete in time, the domain enters a failed state. Click the **Retry** button to restart verification, or remove the domain and add it again.
</Warning>

## Certificate provisioning

After DNS verification succeeds, Unkey provisions a TLS certificate from Let's Encrypt using an ACME HTTP-01 challenge. Frontline serves the challenge token automatically during this process.

Certificates renew before expiration without any action from you.

<Note>
  If Let's Encrypt rate limits are reached, certificate issuance retries automatically with backoff. This can add up to two hours of delay in rare cases.
</Note>

## DNS provider examples

If your provider supports [automatic setup](#configure-dns-records), you can skip these steps and use the one-click **Connect** button instead.

<Tabs>
  <Tab title="Cloudflare">
    1. Open your domain in the Cloudflare dashboard.
    2. Click **DNS** in the sidebar.
    3. Click **Add record**.
    4. Add the TXT record with name `_unkey.{your-subdomain}` and the verification value.
    5. Add the CNAME record with name `{your-subdomain}` and the target from your Unkey dashboard.
    6. Set the CNAME proxy status to **DNS only** (gray cloud) so Unkey can terminate TLS directly.
  </Tab>

  <Tab title="Route53">
    1. Open your hosted zone in the Route53 console.
    2. Click **Create record**.
    3. Add the TXT record with name `_unkey.{your-subdomain}` and the verification value wrapped in quotes.
    4. Add the CNAME record with name `{your-subdomain}` and the target from your Unkey dashboard.
  </Tab>

  <Tab title="Vercel">
    1. Open your domain in the Vercel dashboard under **Settings** > **Domains**.
    2. Click **Manage** next to your domain.
    3. Navigate to the **DNS Records** tab.
    4. Add the TXT record with name `_unkey.{your-subdomain}` and the verification value.
    5. Add the CNAME record with name `{your-subdomain}` and the target from your Unkey dashboard.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Domain stuck in verifying">
    Confirm your DNS records have propagated. TXT records can take up to 48 hours to propagate, depending on your DNS provider. You can check propagation with:

    ```bash theme={"theme":"kanagawa-wave"}
    dig TXT _unkey.api.acme.com
    ```
  </Accordion>

  <Accordion title="Certificate not issued after verification">
    Certificate provisioning starts automatically after both DNS records are verified. If the certificate isn't issued within 30 minutes, check that your CNAME proxy status is set to **DNS only** (not proxied) at your DNS provider.
  </Accordion>

  <Accordion title="Duplicate domain error">
    A domain can only be added once per workspace. If you see a duplicate domain error, check whether the domain already exists in your workspace, possibly in a different project or environment. Remove the existing entry before adding it again.
  </Accordion>
</AccordionGroup>