How to set up a custom API URL

September 9, 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 EU: 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
• 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
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:

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

to:

https://your-custom-domain.com/oauth/code

Step 6: Verify the Setup

1. Test your custom domain by making a simple API call to:
   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)

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:

Type: CNAME
Name: api
Value: api.unified.to
TTL: 3600

OAuth Redirect URL:

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

API Endpoint:

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.