Optional domain verification for login routing and future auto-join functionality.

Email Routing & Auto-Join

Overview

Email routing is an optional convenience feature: by proving ownership of an email domain (e.g. acme.com) with a DNS TXT record, your organization's identity provider is advertised automatically on the login page to anyone who enters an email under that domain — the "type your work email, get sent to your company SSO" experience.

Never an SSO prerequisite

Domain verification is not required to set up Single Sign-On, to JIT-provision members, or to enforce SSO. Registering your IdP — client ID, client secret, callback URL — is enough for a fully working, enforceable SSO connection. Verify a domain only if you want the email-routing convenience (or future auto-join).

Managing domains requires the Owner role (sso.edit) and the Pro plan or above (adding, verifying, or deleting a domain is refused with 403 and {"code": "SSO_NOT_IN_PLAN"} below Pro — see the SSO plan requirement).

What a Verified Domain Unlocks

Login routing advertisement — the email-first login lookup (POST /api/v1/auth/sso/lookup) offers your organization's IdP route to any email under your verified domains, including brand-new users who have never signed in. Without a verified domain, the lookup advertises your IdP only to users who already have an SSO account or whose password account is a member of your organization with enforced SSO.
Future auto-join — domain-based auto-join ("anyone @acme.com joins as Member") will require a verified domain when it ships.

Email routing applies to domain-routed IdP types only: OIDC, SAML 2.0, and Google Workspace. GitHub sign-in is never email-routed — GitHub accounts carry personal email addresses, so there is no domain to route on.

What It Does NOT Gate

Verification proves you control DNS for a domain — nothing more. It is deliberately not used as a security gate anywhere else:

SSO configuration works without any domain (see the setup guides).
JIT provisioning is gated by your IdP itself — whoever your IdP authenticates is whom your organization admits — never by verified domains (details). The optional allowed_email_domains allowlist on the IdP configuration is a declared list, unrelated to the verified routing domains on this page.
Enforced SSO requires an enabled IdP and a proven sign-in, not a verified domain (readiness guards).

Members without an email-routed domain still reach your IdP through the organization sign-in link or the Use single sign-on option — losing or never having a verified domain strands nobody.

Adding and Verifying a Domain

Add the domain:
```
curl -X POST https://app.uptimehunt.io/api/v1/orgs/acme/domains \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'
```
The response includes a txt_record field — the ready-made record value to publish (uptimehunt-verify={verification_token}) — plus the raw verification_token for templating in IaC. The settings page shows the same txt_record value for unverified domains.
Create a DNS TXT record on the domain with the txt_record value:
```
acme.com.  TXT  "uptimehunt-verify={verification_token}"
```

Confirm the record is visible, then trigger verification:

dig +short TXT acme.com | grep uptimehunt-verify

curl -X POST https://app.uptimehunt.io/api/v1/orgs/acme/domains/{id}/verify \
  -H "Authorization: Bearer {access_token}"

Domains can be listed with GET /orgs/{slug}/domains and removed with DELETE /orgs/{slug}/domains/{id}. Keep the TXT record in place — verification may be re-checked.

At most one organization may hold a verified claim on a given domain, so login routing stays deterministic. Verification is required for routing precisely because of what routing advertises: offering "@acme.com → this organization's IdP" to anonymous visitors must be backed by ownership proof, or a hostile organization could capture login routing for a domain it does not own.

DNS propagation

TXT records can take minutes to hours to propagate depending on your DNS provider's TTL. If verification fails, wait and retry.

Removing a Domain

Deleting a domain is always allowed — even the last verified domain of an organization with enforced SSO. Removal only stops the routing advertisement for new visitors; existing members keep their sign-in routes (their SSO accounts already exist, and enforced-organization membership advertises the route by itself).

Auto-Join (Planned)

Domain-based auto-join — automatically adding anyone who signs up with a verified-domain email as a Member — is a planned feature. It will build on verified domains, since capturing every sign-up under a domain requires ownership proof. Until then, membership comes from invitations, JIT provisioning, or GitHub membership mapping.

Email Routing & Auto-Join

On this page