Custom Domains

By default, a WorkOS domain will be used for services such as sending email and hosting AuthKit. In the staging environment these will always use a WorkOS domain, however in production you have the option to provide your own custom domain.

This is a paid service, for which you can find additional details on our pricing page.

Custom domains can be set for:

• Email
• AuthKit
• Admin Portal
• Authentication API

A custom domain can only be configured by one WorkOS team at a time. If a domain is already in use by another team, attempts to configure it will show the domain as unavailable – for example, when the domain was previously set up under a different WorkOS account after a company acquisition or a team split.

If your DNS is managed by Cloudflare, you can proxy an AuthKit, Admin Portal, or Authentication API custom domain through your own Cloudflare zone. Cloudflare calls this setup Orange-to-Orange (O2O). Requests pass through your zone’s rules, such as WAF, bot management, and analytics, before they reach WorkOS.

Keep email domain records DNS-only. Proxying them hides the targets that email providers use to check SPF and DKIM, so email sent from your domain fails authentication.

To proxy an AuthKit, Admin Portal, or Authentication API domain:

1. Create the CNAME record as DNS-only and wait until the domain shows as verified in the WorkOS dashboard.
2. Configure your Cloudflare zone so that requests to the domain reach WorkOS unchanged:
   • Set the SSL/TLS encryption mode to Full (strict).
   • Don’t block, challenge, cache, or redirect the certificate validation paths /.well-known/acme-challenge/*, /.well-known/pki-validation/*, and /.well-known/cf-custom-hostname-challenge/*. WorkOS uses them to issue and renew the domain’s certificate.
   • Don’t apply bot challenges to the ACS URL, where the user’s browser posts SAML responses from the identity provider, or to server-to-server requests, such as SCIM requests and token requests.
   • Bypass the cache for the domain.
   • Don’t rewrite the Host header or use Origin Rules for the domain.
3. Change the CNAME record’s proxy status to Proxied.

Your zone’s rules apply only to requests sent to your custom domain. Requests sent to WorkOS default domains, such as api.workos.com, don’t pass through your zone.