Custom domain setup

The client portal supports both a branded subdomain and custom domains.

Routes involved

• GET /api/client-portal/config?companyId=...
• GET /api/tenants/domains?companyId=...
• POST /api/tenants/domains
• DELETE /api/tenants/domains
• POST /api/tenants/domains/verify
• GET /api/tenants/subdomain
• POST /api/tenants/subdomain/check

What the docs should say

• The company settings page owns the branding and tenant domain records.
• The client portal page reads the active portal config and the current domain list.
• Verification should happen after DNS changes propagate.

Practical setup

1. Pick the branded host you want customers to see.
2. Create the DNS record the app expects.
3. Wait for propagation.
4. Verify the domain in the app.
5. Confirm the portal opens over HTTPS on the final host.

Troubleshooting

• If verification fails, confirm the DNS record target matches what the platform expects.
• If the domain resolves but HTTPS fails, wait for certificate issuance to finish.
• If the portal redirects to the wrong host, check the canonical host and tenant config together.

Document the rollback path as well. Domain changes are high-risk and support needs a clear undo path.