---
title: "How to set up a custom API URL with a CNAME"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_a_custom_api_url_with_a_cname-icon.webp
date: 2025-09-05T00:00:00.000Z
updated: "2026-10-25T20:42:27.522Z"
tag: Guides
integrations: 
description: "This guide walks you through setting up a custom subdomain (CNAME) for your Unified API workspace, so you can use your own domain instead of `api.unified.to`..."
url: "https://docs.unified.to/guides/how_to_set_up_a_custom_api_url_with_a_cname"
---

# How to set up a custom API URL with a CNAME
------
_September 5, 2025_

This guide walks you through setting up a custom subdomain (CNAME) for your Unified API workspace, so you can use your own domain instead of `api.unified.to` for API calls and OAuth flows.


> 💡 This is mandatory when using Sensitive scopes in any of the Google integrations. It allows the Google verification to pass.


## Prerequisites

- A Pro or Scale plan (custom domains are not available on Grow)
- A workspace in the US or EU region (custom domains are not yet available in the AU region)
- Access to your domain's DNS management console
- Admin access to your Unified workspace

## Step 1: Choose your custom subdomain


Pick the subdomain you want to use, for example:

- `api.yourcompany.com`
- `unified-api.yourcompany.com`
- `integrations.yourcompany.com`

## Step 2: Create the CNAME record

1. Log in to your DNS provider (e.g. Cloudflare, GoDaddy, Namecheap, AWS Route 53).
2. Go to DNS management for your domain.
3. Add a CNAME record:
    - **Type**: CNAME
    - **Name**: your subdomain (e.g. `api` or `unified-api`)
    - **Value/Target**, for your workspace's region:
        - US: `unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com`
        - EU: `unified-domains-eu-a0f8a17b303a3c06.elb.eu-central-1.amazonaws.com`
    - **TTL**: 3600 (or default)
    - **Proxy status**: DNS only / disabled (if using Cloudflare). A proxied record hides the CNAME, so it can't be verified, and it blocks the TLS certificate from being issued.
4. Save the record.

The target is also shown on the **Custom domains** settings page, in the help text of the **Custom API domain** field.


## Step 3: Wait for DNS propagation


DNS changes can take from a few minutes to 48 hours to propagate. You can check with [whatsmydns.net](https://whatsmydns.net/) or [dnschecker.org](https://dnschecker.org/): the CNAME for your subdomain should show the target above.


## Step 4: Update your OAuth applications


**Important**: as soon as your domain is saved in Step 5, OAuth flows redirect to it. To avoid failed authorizations, add the new redirect URI to every OAuth application you use with Unified _before_ Step 5 (most providers allow several), then remove the old one once everything works.


Add:


```plain text
https://api.yourcompany.com/oauth/code
```


alongside:


```plain text
https://api.unified.to/oauth/code
```


## Step 5: Add the domain to your workspace

1. Go to [Settings → Custom domains](https://app.unified.to/settings/branding) (use [app-eu.unified.to](https://app-eu.unified.to/settings/branding) for EU workspaces).
2. Enter your subdomain in **Custom API domain**, without `https://` (e.g. `api.yourcompany.com`).
3. Click **Verify** (or **Save changes**).

Unified checks that the CNAME points to your region's target. If it does, the domain shows as **Verified** and Unified adds it to its load balancer. A TLS certificate is issued automatically, usually within a few minutes.


If the CNAME isn't in place yet, you'll see an error explaining what's missing. Wait for DNS to propagate and click **Verify** again.


To stop using a custom domain, clear the field and click **Save changes**.


## Step 6: Check the setup

1. Open `https://api.yourcompany.com/swagger.json`. It should load over HTTPS. If you get a certificate error, wait a few minutes for the certificate to be issued.
2. Authorize a test connection to an OAuth integration and confirm the redirect works.

## Important notes


### OAuth verification

- **Google OAuth**: after changing the redirect URI, you may need to complete app verification again, since Google sees it as a new domain ([Google's verification guide](https://support.google.com/cloud/answer/13461325)).
- **Other providers** may require similar verification.

### API usage

- Your API calls can use your custom domain. API functionality is identical.
- API keys and authentication don't change.

### Security

- Protect access to your DNS provider and consider enabling DNSSEC.
- Monitor for unauthorized DNS changes.

## Troubleshooting

1. **"does not have a CNAME record pointing to …"**
    - DNS hasn't propagated yet, or the record points somewhere else. Make sure the target matches your workspace's region exactly and that Cloudflare proxying is off.
2. **"is already used by another workspace"**
    - Each custom domain can belong to one workspace. Contact Unified Support if you need to move it.
3. **Certificate error on your domain**
    - The certificate is issued a few minutes after verification. If it still fails after an hour, contact Unified Support.
4. **OAuth errors after the change**
    - Make sure redirect URIs are updated in all OAuth applications, and complete app verification if the provider requires it.

## Example


For `api.yourcompany.com` in the US region:


```plain text
Type: CNAME
Name: api
Value: unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com
TTL: 3600
```


OAuth redirect URI: `https://api.yourcompany.com/oauth/code`


API endpoint: `https://api.yourcompany.com/crm/{connection_id}/contact`