---
title: "How to set up a custom API URL"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_set_up_a_custom_api_url-icon.webp
date: 2025-09-05T00:00:00.000Z
tag: Guides
description: "This guide will walk you through the process of setting up a custom CNAME (subdomain) for your Unified API workspace. This allows you to use your own domain..."
url: "https://docs.unified.to/guides/how_to_set_up_a_custom_api_url"
---

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

This guide will walk you through the process of setting up a custom CNAME (subdomain) for your Unified API workspace. This allows you to use your own domain instead of the default `api.unified.to` domain for all API calls and OAuth flows.


> 💡 This is mandatory when using Sensitive scopes in any of the Google integrations, doing this will allow the Google verification to pass.


## Prerequisites

- You must have a paid Unified plan (custom domains are not available on the free/test plan)
- Access to your domain's DNS management console
- Admin access to your Unified workspace

## Step 1: Choose Your Custom Subdomain


Decide on a subdomain you want to use. For example:
- `api.yourcompany.com`
- `unified-api.yourcompany.com`
- `integrations.yourcompany.com`


## Step 2: Configure DNS CNAME Record

1. **Log into your domain registrar or DNS provider** (e.g., Cloudflare, GoDaddy, Namecheap, AWS Route 53)
2. **Navigate to DNS management** for your domain
3. **Add a new CNAME record** with the following settings:
    - **Type**: CNAME
    - **Name**: Your chosen subdomain (e.g., `api` or `unified-api`)
    - **Value/Target**: 
    US: [unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com](https://unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com/)
    EU: [unified-domains-eu-a0f8a17b303a3c06.elb.eu-central-1.amazonaws.com](https://unified-domains-eu-a0f8a17b303a3c06.elb.eu-central-1.amazonaws.com/)
    - **TTL**: 3600 (or default)
    - **Proxy status**: Disabled (if using Cloudflare)
4. **Save the CNAME record**

## Step 3: Wait for DNS Propagation


DNS changes can take anywhere from a few minutes to 48 hours to propagate globally. You can check propagation using tools like:
- [whatsmydns.net](https://whatsmydns.net/)
- [dnschecker.org](https://dnschecker.org/)


## Step 4: Contact Unified Support


Once your CNAME is configured and propagated:

1. **Contact Unified Support** through your preferred channel
2. **Provide the following information**:
    - Your workspace name/ID
    - The custom subdomain you want to use
    - Confirmation that the CNAME is configured and pointing to [unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com](https://unified-domains-us-7d67c6f04efebb36.elb.us-east-1.amazonaws.com/)
3. **Support will assign the custom domain** to your workspace

## Step 5: Update OAuth Application Settings


**CRITICAL**: After your custom domain is assigned, you must update all OAuth applications to use the new redirect URL.


### For OAuth Applications:

1. Go to yor app Console
2. Update the **Authorized redirect URIs** from:

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


to:


```plain text
https://your-custom-domain.com/oauth/code
```


## Step 6: Verify the Setup

1. **Test your custom domain** by making a simple API call to:

    ```plain text
    https://your-custom-domain.com/swagger.json
    ```

2. **Test OAuth flow** by attempting to authenticate with an integration using your custom domain
3. **Verify redirect URLs** are working correctly in your OAuth applications

## Important Notes


### OAuth Verification Requirements

- **Google OAuth**: After changing the redirect URL, you may need to complete app verification since Google sees this as a new domain
- **Other providers**: May require similar verification processes
- **App verification**: Follow the provider's specific verification process (e.g., [Google's verification guide](https://support.google.com/cloud/answer/13461325))

### API Usage

- All API calls will now use your custom domain
- The API functionality remains identical
- Your API keys and authentication methods remain the same

### Security Considerations

- Ensure your DNS provider has proper security measures
- Consider enabling DNSSEC if available
- Monitor for any unauthorized DNS changes

## Troubleshooting


### Common Issues

1. **DNS Not Propagated**
    - Wait longer for propagation
    - Check with multiple DNS lookup tools
    - Verify CNAME record is correct
2. **OAuth Errors After Domain Change**
    - Ensure redirect URLs are updated in all OAuth applications
    - Complete app verification if required by the provider
    - Check that the custom domain is properly assigned to your workspace
3. **API Calls Failing**
    - Verify the CNAME is pointing to `api.unified.to`
    - Check that the custom domain is assigned to your workspace
    - Ensure your API keys are still valid

## Example Configuration


Here's a complete example for setting up `api.yourcompany.com`:


### DNS Configuration:


```plain text
Type: CNAME
Name: api
Value: api.unified.to
TTL: 3600
```


### OAuth Redirect URL:


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


### API Endpoint:


```plain text
https://api.yourcompany.com/v1/your-endpoint
```


---


**Note**: Custom domain setup requires coordination with Unified Support to ensure proper configuration and security. Please allow 1-2 business days for the setup to be completed after your CNAME is configured.