Custom Domain Configuration

Critical setup steps for enabling authentication on custom domains.

Overview

Each workspace in the 1 OAK MLS Platform can have one or more custom domains. For authentication (magic links, OAuth) to work correctly on these domains, they must be whitelisted in Supabase.

This is a manual step required for every new custom domain.

The Problem

When a custom domain is not configured in Supabase:

1. User visits custom-domain.1oakmls.com/login
2. Enters email, requests magic link
3. Supabase sends email with auth link
4. User clicks link → Redirected to wrong domain (fallback Site URL)
5. User lands on homepage, not authenticated

This happens because Supabase rejects redirect URLs that aren't in the allow list and falls back to the configured Site URL.

Supabase Redirect URL Configuration

Adding a New Custom Domain

1. Go to Supabase Dashboard → Authentication → URL Configuration

2. Under Redirect URLs, click "Add URL"

3. Add the domain with a wildcard path:

   https://custom-domain.1oakmls.com/**

4. Click Save

Recommended URL Patterns

For each workspace domain, add:

Example for a workspace with custom domain agent-site.com:

https://agent-site.com/**
https://workspace-slug.yourdomain.com/**

Wildcard Subdomain (Optional)

If using a consistent subdomain pattern like [slug].1oakmls.com, you can add a wildcard:

https://*.1oakmls.com/**

Note: This may have security implications. Consider whether you trust all possible subdomains.

Workspace Onboarding Checklist

When setting up a new workspace, complete these steps:

1. Create Workspace (Admin App)

• Create workspace in admin at /admin/workspaces/new
• Set workspace name and slug
• Configure MLS connection

2. Configure DNS

• Add custom domain to workspace in admin
• Configure DNS CNAME record pointing to Vercel
• Verify domain in Vercel dashboard

3. Enable Authentication (Supabase)

• Add redirect URL to Supabase: https://[domain]/**
• Test magic link authentication on the domain

4. Verification

• Visit https://[domain]/login
• Send magic link to test email
• Click link and verify redirect goes to correct domain
• Confirm user is authenticated and sees dashboard

Tracking Domains

Keep a record of configured domains for each workspace:

Note: Maintain this list internally or in a separate tracking document.

Troubleshooting

Magic link redirects to wrong domain

Cause: Domain not in Supabase Redirect URLs

Fix: Add https://[domain]/** to Supabase → Authentication → URL Configuration

Magic link goes to correct domain but lands on homepage

Cause: Redirecting to root / instead of /auth/callback

Fix: Check that the callback URL in the login form includes the full path:

redirectTo: `${window.location.origin}/auth/callback`

User authenticated but immediately logged out

Cause: Cookie domain mismatch or middleware issue

Fix:

• Verify Supabase client is using correct cookie settings
• Check middleware allows /auth/callback route

Technical Details

How Magic Link Authentication Works

1. User submits email on /login
   └─ signInWithOtp({ redirectTo: 'https://custom.com/auth/callback' })

2. Supabase checks if redirect URL is allowed
   ├─ If allowed → Sends email with link to that URL
   └─ If NOT allowed → Falls back to Site URL (wrong domain!)

3. User clicks magic link
   └─ Redirected to /auth/callback?code=...

4. Callback route exchanges code for session
   └─ supabase.auth.exchangeCodeForSession(code)

5. User redirected to /dashboard (authenticated)

Relevant Code Files

Future Improvements

Consider automating domain registration:

1. Admin Trigger: When a domain is added in the admin app, trigger a webhook
2. Supabase Management API: Use the API to add the redirect URL automatically
3. Verification: Confirm the URL was added successfully

This would eliminate the manual Supabase dashboard step and reduce onboarding friction.

Related Documentation

• Admin UI - Admin UI for workspace management
• Supabase Auth Docs - Official redirect URL documentation