Custom Domains
Configure custom domains for enterprise workspaces so users access Atlas at your own URL.
Custom domains let workspaces use their own URL (e.g. data.acme.com) instead of the default app.useatlas.dev. Atlas integrates with Railway's custom domain API for provisioning and automatic TLS certificate management via Let's Encrypt.
SaaS Feature
Custom domains are available on app.useatlas.dev Enterprise plans. Self-hosted deployments configure domains directly in their hosting provider. Workspace admins can self-serve via Admin Console → Configuration → Custom Domain. Platform admins retain cross-workspace management at Admin Console → Platform → Custom Domains.
Prerequisites
- Active Enterprise plan on app.useatlas.dev (or self-hosted "free" tier)
- Internal database configured (
DATABASE_URL) - Admin role (workspace admin for self-serve, platform admin for cross-workspace management)
- Railway deployment with API token configured
How It Works
| Step | What Happens |
|---|---|
| Register | Admin registers a domain in the Atlas admin console. Atlas calls Railway to provision it |
| Configure DNS | Admin creates a CNAME record pointing their domain at the Railway target |
| Verify | Admin clicks "Verify" — Atlas checks Railway for DNS propagation and TLS certificate status |
| Route | Once verified, requests to the custom domain are routed to the correct workspace |
Railway handles TLS certificate provisioning automatically. Atlas stores the domain-to-workspace mapping for host-based routing.
Configuration
Environment Variables
Add these to your .env file (get values from your Railway dashboard):
# Railway custom domain API
RAILWAY_API_TOKEN=your-workspace-scoped-token
RAILWAY_PROJECT_ID=your-project-id
RAILWAY_ENVIRONMENT_ID=your-environment-id
RAILWAY_WEB_SERVICE_ID=your-web-service-id| Variable | Description |
|---|---|
RAILWAY_API_TOKEN | Workspace-scoped API token from Railway dashboard → Settings → Tokens |
RAILWAY_PROJECT_ID | Project ID from your Railway project settings |
RAILWAY_ENVIRONMENT_ID | Environment ID (typically production) |
RAILWAY_WEB_SERVICE_ID | Service ID for the web service that should receive custom domain traffic |
Workspace Admin (Self-Serve)
Workspace admins on Enterprise plans can manage their own custom domain at Admin Console → Configuration → Custom Domain. One domain per workspace (MVP).
Adding a Domain
- Navigate to Admin Console → Configuration → Custom Domain
- Enter your domain (e.g.
data.acme.com) - Click Add Domain
- Atlas registers the domain and shows DNS configuration instructions
DNS Setup
After adding, set up a CNAME record with your DNS provider:
| Record Type | Name | Value |
|---|---|---|
| CNAME | data.acme.com | <target>.up.railway.app (shown in the admin page) |
Click the copy button next to the CNAME target to copy it.
Checking Status
- After creating the DNS record, wait a few minutes for propagation
- Click Check Status on the domain page
- Status updates to Active (green) once DNS is propagated and TLS certificate is issued
Removing a Domain
Click Remove Domain and confirm. This removes the domain from both Railway and Atlas.
Plan Gating
Non-enterprise workspaces see an upgrade prompt instead of the domain form. Self-hosted deployments (which default to the "free" tier) can use custom domains without plan restrictions.
Platform Admin (Cross-Workspace)
Platform admins retain full domain management across all workspaces at Admin Console → Platform → Custom Domains.
Registering a Domain
- Click Add Domain
- Enter the Workspace ID and Domain (e.g.
data.acme.com) - Click Register Domain
- Atlas creates the domain in Railway and shows the CNAME target
Verification
- After creating the DNS record, wait a few minutes for propagation
- Click the refresh icon next to the domain in the admin table
- Atlas checks Railway for DNS propagation and certificate status
- Status updates to Verified (green) once DNS is propagated and TLS certificate is issued
Status Badges
| Status | Meaning |
|---|---|
| Pending (yellow) | Domain registered, waiting for DNS setup or certificate provisioning |
| Verified / Active (green) | DNS verified and TLS certificate issued — domain is live. API returns "verified" status; workspace UI displays "Active" |
| Failed (red) | DNS verification or certificate provisioning failed |
Deleting a Domain
Click the trash icon next to any domain. This removes the domain from both Railway (revoking the TLS certificate) and Atlas.
Host-Based Routing
When a request arrives on a custom domain, Atlas:
- Looks up the hostname in the
custom_domainstable (with 60-second cache) - If a verified match is found, sets the workspace context to the owning workspace
- All subsequent operations (queries, conversations, etc.) are scoped to that workspace
API Reference
Workspace Admin Endpoints
Require admin role and active organization. Enterprise plan required for adding a domain (POST /api/v1/admin/domain).
| Method | Path | Description |
|---|---|---|
GET | /api/v1/admin/domain | Get workspace custom domain (null if none) |
POST | /api/v1/admin/domain | Add a custom domain ({ domain }) |
POST | /api/v1/admin/domain/verify | Check verification status |
DELETE | /api/v1/admin/domain | Remove workspace custom domain |
Platform Admin Endpoints
Require platform_admin role and enterprise features.
| Method | Path | Description |
|---|---|---|
GET | /api/v1/platform/domains | List all custom domains |
POST | /api/v1/platform/domains | Register a domain ({ workspaceId, domain }) |
POST | /api/v1/platform/domains/:id/verify | Check verification status |
DELETE | /api/v1/platform/domains/:id | Delete a domain |
Troubleshooting
Domain stays in "Pending" status
- Verify your CNAME record is correctly configured with your DNS provider
- DNS propagation can take up to 48 hours (though usually minutes)
- Check that the CNAME target matches exactly what Atlas shows in the admin UI
- Click the verify button again after waiting
Certificate status shows "Failed"
- Ensure no CAA records on your domain block Let's Encrypt (
letsencrypt.org) - Verify no conflicting A or AAAA records exist for the same hostname
- Delete and re-register the domain if the issue persists
"Railway API is not configured" error
- Ensure all four Railway environment variables are set:
RAILWAY_API_TOKEN,RAILWAY_PROJECT_ID,RAILWAY_ENVIRONMENT_ID,RAILWAY_WEB_SERVICE_ID - Verify the API token has workspace-level permissions in Railway
"Domain is not available" error
- The domain may already be registered in another Railway project
- Check Railway dashboard for existing custom domain entries