Verified Domains

Verified Domains let organization owners and admins on Enterprise plans prove they control an email domain (like acme.com) with a DNS TXT record. Verify a domain before configuring single sign-on for it or provisioning members at that domain through SCIM.

Configuring SSO for a domain requires it to be verified first. Verifying proves your organization controls the domain — without it, anyone could point another company's domain at their own identity provider. The domain-verification migration preserved domains configured for SSO before this requirement was introduced.

Verify a domain

Go to Settings → Organization → Single sign-on → Domains. The Verified domains section is shared by sign-in and directory provisioning.

  1. Enter the domain, for example acme.com, and click Add domain.
  2. Agent Serve shows a DNS TXT record to publish — a host (_agentserve-challenge.acme.com) and a unique value (agentserve-domain-verification=…).
  3. Add that TXT record at your DNS provider.
  4. Click Verify. Agent Serve looks up the record; on success the domain is marked Verified.

Some DNS providers append the zone automatically. If yours does, enter _agentserve-challenge when managing the acme.com zone, or _agentserve-challenge.eng to verify eng.acme.com from that zone. Check the resulting record name: it must match the full host Agent Serve shows, without a repeated domain such as _agentserve-challenge.acme.com.acme.com.

DNS changes can take time to propagate. If verification does not succeed immediately, check the record name and value, then wait and retry. Keep the TXT record published. Agent Serve verifies it when you select Verify; removing the DNS record does not itself revoke a completed verification.

Add each domain you own separately. Subdomains (eng.acme.com) are verified independently of the apex.

FAQ

Common Questions

On the dedicated host _agentserve-challenge.<your-domain>. Add the supplied TXT value there without replacing existing records on your domain.
Domains configured before domain verification was introduced were preserved as verified by the migration. New domains must complete DNS verification.
No. A verified domain belongs to exactly one organization. Once verified, another organization cannot claim it.
New SSO sign-ins for that domain stop immediately, including through an existing provider. SCIM cannot create users or change an email to that domain until it is verified again. Removing the domain does not itself end existing sessions. Re-add and verify it to restore the ownership proof.

Self-hosted setup

Domain verification appears on the single sign-on page when SSO is enabled:

SSO_ENABLED=true
NEXT_PUBLIC_SSO_ENABLED=true

ENTERPRISE_ENABLED turns both on together, but it needs its own browser twin — set NEXT_PUBLIC_ENTERPRISE_ENABLED alongside it, or the server and the settings page enable SSO while the login page still hides its SSO entry point. See the self-hosted enterprise guide.

Once enabled, verify domains from Settings → Organization → Single sign-on → Domains. The older /workspace/<workspaceId>/settings/domains path still resolves to the same page.

Restricted networks

Agent Serve queries 1.1.1.1 and 8.8.8.8 directly from the application server. Allow outbound DNS on UDP and TCP port 53 to these addresses. The lookup uses public DNS rather than the server's local resolver or an HTTP proxy, so the TXT record must be published in a publicly delegated DNS zone. A Route 53 private hosted zone is not visible to these resolvers.

Skip DNS verification

For a deployment where the operator trusts every organization owner and admin to claim email domains, set this server-only variable and restart the application:

SSO_SKIP_DOMAIN_VERIFICATION=true

For Helm deployments, use an application image built from a revision that includes this setting. Upgrading the chart alone does not make an older application image support the variable. Override app.image.tag with a compatible released image or a build you publish yourself; set app.image.repository as well for a custom repository:

app:
  image:
    tag: "<image-tag-with-domain-verification-bypass>"
  env:
    SSO_SKIP_DOMAIN_VERIFICATION: "true"

If app.image.digest is set, replace it with a compatible image digest instead — it takes precedence over the tag.

Add the domain under Domains, then click Verify. No TXT record or DNS access is needed. The domain is recorded as verified for SSO account linking and SCIM provisioning, and another organization still cannot claim the same domain. Existing pending domains can be verified the same way.

This option is off by default and ignored on Agent Serve Cloud. It applies to every organization in the self-hosted instance: an organization administrator can authorize their identity provider for any unclaimed email domain without proving ownership. Enable it only when those administrators are trusted to make that decision.

Removing the variable or setting it to false restores DNS verification for pending and future claims. Domains already verified remain verified; remove a domain in Domains to revoke its trust.

Microsoft Entra provisioningSecurity