Custom signing domains

Organizations can give signers their own address, such as sign.customer.com, in Admin → Settings (see Organization settings). Signing emails then link to that address, and the signer pages are served on it. Staff keep using the app in Teams and at APP_URL.

This uses Cloudflare for SaaS custom hostnames: the customer adds a CNAME record to a hostname on your Cloudflare zone, Cloudflare validates it and issues the certificate, and forwards the requests to your server with the customer’s hostname.

1. Put your domain on Cloudflare and enable SSL/TLS → Custom Hostnames (Cloudflare for SaaS) on the zone.
2. Create the fallback origin: a proxied DNS record that points to your server, for example origin.example.com, and set it as the fallback origin under Custom Hostnames. Your server answers for any hostname, so nothing else is needed there.
3. Create the CNAME target customers point at, for example customers.example.com, as a proxied CNAME to the fallback origin.
4. Create an API token with the zone permission SSL and Certificates: Edit, limited to this zone.
5. Configure the API:

   CLOUDFLARE_API_TOKEN=…
   CLOUDFLARE_ZONE_ID=…            # Overview page of the zone
   CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

   With CLOUDFLARE_API_TOKEN set, CUSTOM_DOMAINS defaults to cloudflare. Set CUSTOM_DOMAINS=off to hide the feature.

How it behaves

• Validation and certificates use Cloudflare’s HTTP validation, so the customer’s CNAME record is the only DNS change. The API checks pending domains every 5 minutes, and Tenant Owners can choose Check now.
• Links in invitations, reminders and completion emails use the custom domain only while it’s active. The in-app Sign now link for colleagues keeps using APP_URL, so it works inside Teams.
• On a custom domain the server serves only the signer pages and their API, and only for that organization’s signing requests. Other app pages redirect to APP_URL; other API calls return 404.
• Removing a domain deletes the custom hostname in Cloudflare. Links in emails already sent with that domain stop working, and the settings page warns about this.

Note

Set TRUST_PROXY to match your setup so the server sees the original hostname. Requests through Cloudflare carry the customer’s hostname in the Host header.

Development

Without CLOUDFLARE_API_TOKEN, development uses a simulated Cloudflare (CUSTOM_DOMAINS=fake): a domain you add is pending until the first Check now, then active. fake isn’t allowed in production.