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 or 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:

https://api.yourcompany.com/oauth/code

alongside:

https://api.unified.to/oauth/code

Step 5: Add the domain to your workspace

1. Go to Settings → Custom domains (use app-eu.unified.to 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).
• 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:

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