Set up a custom domain

What a custom domain gives you

Every organization has a permanent URL at {slug}.taskjuice.ai. A custom domain adds a second hostname (for example, automations.agency.com) that keeps your brand in the address bar for sign-in, workflows, and every page your clients see.

The permanent URL never goes away. If DNS takes time to propagate, if a record expires, or if you remove the custom domain later, your team and your clients can still reach the app at {slug}.taskjuice.ai.

Before you start

• You need a domain you control (you can add records at its DNS provider).
• Use a subdomain like app.agency.com or automations.agency.com. Root domains (agency.com, or agency.co.uk where the suffix has two parts) are rejected when you enter them, because a CNAME at the root of a domain conflicts with its other records, including email MX.
• One custom domain per organization. To change hosts later, remove the existing one first. Each client can also get a domain of its own: see Client domains.

Step 1: Enter your hostname

1. Open domain settings

   Sign in to your organization and go to Settings → Domain, or visit /settings/domain directly from any page.

2. Add your hostname

   Type the full hostname (for example, automations.agency.com) into the Hostname field and click Add domain. The page switches to a guided card that shows you the exact DNS records to add.

Nothing is routing yet. Adding the domain just registers your claim and generates the ownership token you'll prove in the next step.

Step 2: Prove ownership with a TXT record

The guided card shows you a single TXT record. Copy both values into your DNS provider's zone for the domain.

Host:  _taskjuice-verify.automations.agency.com
Type:  TXT
Value: a4f9e2d1-5c3b-4e87-9d21-1f8c7e2b3a9f   (your actual token will differ)

TaskJuice checks for this record every 5 minutes. Once the record resolves and the value matches, the first step on the guided card flips to a green check.

Step 3: Point traffic with a CNAME record

Once ownership is proven, the guided card reveals a second record — the CNAME that actually routes traffic to TaskJuice.

Host:  automations.agency.com
Type:  CNAME
Value: <shown in the guided card>

Add this record alongside the TXT record. Do not remove the TXT record — TaskJuice re-checks it periodically and a domain whose ownership lapses will be flagged as unreachable.

Step 4: Wait for the certificate

As soon as the CNAME resolves, TaskJuice requests a TLS certificate for your hostname and installs it automatically. No action required. The guided card's third step shows a loading state, then flips to green with the date it activated. Most certificates issue within five minutes.

When the card shows Active, open https://automations.agency.com in a new tab. You should land on your TaskJuice workspace with a valid TLS certificate.

Fix a dns_failed or ssl_failed domain

When a previously active domain stops resolving or its certificate can't renew, the status card switches to red and a banner appears on every page of your workspace. Your permanent URL still works; only clients using the custom hostname are affected.

1. Confirm the DNS records at your provider

   Open your DNS provider and verify both the TXT and CNAME records are still present with the exact values from the domain settings page. A common cause is a provider's auto-cleanup or a migration that silently drops older records.

2. Re-check without waiting for the cron

   On the status card, click Recheck now. TaskJuice queues an immediate verification instead of waiting for the next 5-minute window. This button is rate-limited to one call every 30 seconds per organization.

3. If the records look right but still fail

   Wait for DNS caches at your provider to expire. TTL on your records controls this — most providers use 300-3600 seconds. Rechecking won't help until the cached miss times out.

Remove a custom domain

Click Remove domain on the status card and confirm. Clients using the custom hostname will stop reaching your workspace within 15 minutes as DNS caches expire. Your permanent URL is unaffected.

After removal, you can add the same hostname or a different one from the empty-state card.

Client domains

A client domain gives one of your clients an address of their own, like hub.acmeplumbing.com. That client's portal and approval links live there, and the client's sign-in page carries the client's brand. Your organization's address stays yours.

• Business plan. Client domains come with the same plan as your organization's custom domain. On a lower plan the add button reads Upgrade to add a domain and opens the upgrade dialog.
• Owners and Admins only. Other roles don't see the card.
• One domain per client. To change it, remove the current one first.
• Subdomains only. Use a subdomain like hub.acmeplumbing.com or portal.acmeplumbing.com. Root domains like acmeplumbing.com are rejected.
• One owner per hostname. A hostname that already belongs to your organization, to another client or to another account is rejected as already in use.

Set up a client domain

1. Open the client's workspace settings

   In the client's workspace, go to Settings → Domains and find the Client domain card. The tab is listed for account owners and admins only.

2. Add the hostname

   Type the full hostname (for example, hub.acmeplumbing.com), wait for Ready under the field, then click Add domain. The card switches to a guided setup with a progress stepper and the DNS records to add.

3. Add the DNS records

   Add every record the card lists at the company that manages DNS for the client's domain. If someone else manages it, send them the records (see the next section).

4. Wait for the client domain to go live

   The stepper moves through DNS validation, Certificate issued, Traffic DNS and Live. When the card shows Active, the client's portal and approval links are live on the client domain. Check now asks for an immediate recheck instead of waiting for the next scheduled one.

The card lists three records, in this order. The validation record can take a few seconds to appear after you add the domain. Some values are unique to each domain, so copy them from the card rather than from this page.

A setup whose records are not verified within 14 days expires; the card shows the date from day 7, and you add the domain again after it expires. If the card reports that it couldn't verify the DNS, fix the records, then click Reset and try again.

Send the records to whoever runs the client's DNS

If you don't hold the login for the client's DNS, use the Someone else runs {client}'s DNS? row under the records. It offers two ways to hand the records over, and both turn on once all three records are on the card.

Email these steps sends one email, from your organization, that lists the records as Type, Name and Value with plain instructions. Type the address of the client's IT contact; the button turns on once the address is valid, and Sent to confirms the send. Your organization can send these emails up to 10 times an hour, across all of its domains. If the address has bounced before or marked your mail as spam, nothing is sent and the card asks you to try another address.

Copy all records copies the records as lines, one per record, with Type, Name and Value separated by tabs. The lines paste as columns into a spreadsheet or into a DNS provider's bulk import box.

The row disappears once the client domain is active.

What your client sees

• Their portal. Opening https://hub.acmeplumbing.com goes straight to that client's portal, unless you have published a home page for the client, which shows there instead; the portal stays at https://hub.acmeplumbing.com/portal. A person who is a client of two of your workspaces sees only this client's portal on this client domain.
• Approval links and client emails. Approval links sent to the client open on the client domain. The links in the client's invoices, work requests and connection requests use the client domain while it is active, and your organization's address otherwise.
• Their brand on the sign-in page. The sign-in page shows the client's logo and accent color, with "by" and your organization's name under the logo. A client without branding of their own sees your organization's brand. Set a client's brand in the client's workspace settings; see Branding.
• Only their own people. Only that client's portal users can sign in on the client domain.

Forms open on the client domain too. A form you assign to the client's workspace (see Assign a form to a workspace) shares on the client domain while it is active: the share links in the form editor use its address, and your organization's address otherwise.

What your team sees

The client domain belongs to the client, so it never serves your organization's console. A teammate who opens a page that is not part of the client's portal, such as your dashboard or workflows, is sent to the same page on your organization's permanent URL ({slug}.taskjuice.ai). The client domain's own address shows the client's sign-in page, and when a teammate signs in there, TaskJuice refuses the sign-in and sends them to your organization's sign-in page.

Add client domains to Google sign-in

Once your organization has set up Google sign-in, the Google sign-in card in the Authentication section of Settings → Domains lists one sign-in redirect URI for your organization's custom domain and one for each active client domain. Add every URI the card lists under Authorised redirect URIs in your Google Cloud OAuth client, or Google refuses sign-in on any client domain you left out.

Setting up Google sign-in needs your organization's custom domain to be active. Until Google sign-in is set up, clients sign in on their client domain with email and password.

Remove a client domain

Click Remove domain on the client domain card (Remove while the domain is still being set up or has failed), type the hostname to confirm, and click Remove domain in the dialog. The client domain stops serving the client's portal and approval links, its certificate is deleted, and new links go back to your organization's address.

Deleting the client's workspace releases its domain the same way. The same client can add its hostname back right away. Another client, or your organization, can add it a few minutes after the removal finishes.

Errors when adding a client domain

These messages appear under the hostname field while TaskJuice checks it, before Add domain turns on.

Troubleshooting

The TXT record doesn't verify after 30+ minutes. Confirm the record name includes the _taskjuice-verify. prefix — some DNS provider UIs quietly strip leading underscores. Also confirm your provider added the record at the apex of the correct zone. If you added it to a different zone (for example, _taskjuice-verify.automations.agency.com in the agency.com zone instead of a delegated automations.agency.com zone), the lookup won't resolve.

The CNAME doesn't activate the domain. CNAME records can only be added at subdomains, never at the apex. If your DNS provider shows an error like "CNAME conflicts with SOA record," you're trying to add it at the root of the zone. Use a subdomain like app.agency.com.

The certificate is stuck issuing. Issuing requires the CNAME to resolve first. If the traffic CNAME isn't in place, or points at an old value, the certificate can't complete. Confirm the CNAME value matches exactly what the guided card shows — TaskJuice rotates it rarely, but if you copied the value before ownership was proven, re-check the card.

The domain auto-removed before I could fix it. Abandoned domains (stuck in pending for 14 days) or long-failed domains (stuck in failed for 30 days) are cleaned up automatically. To restore, add the domain again from /settings/domain. All DNS records need to be re-added because the ownership token regenerates on each add.

What a custom domain does not change

• Your permanent subdomain. {slug}.taskjuice.ai stays live forever.
• Webhook URLs. Webhook triggers continue to accept traffic at api.taskjuice.ai. End clients paste these URLs into third-party dashboards where branding rarely matters, so they stay on the canonical host.
• Your admin login. The Payload admin UI at taskjuice.ai/admin is super-admin only and is never exposed on a custom domain.
• Email sender addresses. Transactional email continues to come from a @taskjuice.ai address. White-label sender domains are a separate feature.

Next steps

• Review Branding settings to match the app's colors and logo to your organization's brand.
• If you haven't connected a first integration yet, see the Quickstart.