---
title: "Email domains"
description: "Prove your directory owns an email domain with a DNS TXT record, so people in it can sign in through your identity provider."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.ezghcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email domains

Before people can sign in through an [identity provider](/sso/identity-providers), your directory
must prove it owns their email domain. A verified domain can be routed to one identity provider;
everyone whose email address is in it is then sent there to sign in, and can be created on their
first sign-in. The identity provider's [SCIM](/sso/scim) can provision only people in the domains
routed to it. Unverified domains do nothing.

These are the directory's own domains, separate from the verified domains of
[IAM's directory](/iam/directory), which are for your members' console sign-in. If you use both,
verify the domain in each.

## Add a domain

```sh
ezgh sso domains create acme.com
```

Or call [CreateDomain](/sso-api/CreateDomain/) with `{ "domain": "acme.com" }`. The domain
is `pending`, and the answer's `verification` names the DNS record to publish:

| Record | Name | Value |
| --- | --- | --- |
| `TXT` | `_ezgh-sso-verification.acme.com` | `ezgh-sso-verification=<token>` |

- A domain is lowercase ASCII with at least two labels; write an internationalized domain in its
  `xn--` form. EZGH's own domains are refused.
- Routing matches the email address's domain exactly: `acme.com` doesn't cover
  `ada@eu.acme.com`. Add and verify each domain your people use.
- A directory has at most 50 domains (`409 too_many_domains`).

## Verification

EZGH SSO looks for the record as soon as you add the domain, then every 15 minutes for a week.
[VerifyDomain](/sso-api/VerifyDomain/) (`ezgh sso domains verify acme.com`) asks for a check
within seconds, and restarts the week. Once the record is found, the domain is `verified`.
After a week without it, the domain stays `pending` until you ask for another check.

[GetDomain](/sso-api/GetDomain/) shows `status`, `verifiedAt`, `lastCheckedAt` and
`checkError` (why the last check didn't verify it).

Keep the record published. A verified domain is checked again every 6 hours; if the record is
missing twice in a row (15 minutes apart), the domain goes back to `pending`, and from then it no
longer routes anyone, creates users or lets SCIM provision people in it. A DNS failure or timeout
changes nothing. Each change is recorded in [Trails](/sso/trails) as `UpdateDomainVerification`.

## One directory per domain

A domain is verified in at most one directory. Another directory can add the same domain and
publish its own record, but it stays `pending`, with `checkError` saying the domain is verified
in another directory, until the first directory removes it or loses its verification.

## Remove a domain

[DeleteDomain](/sso-api/DeleteDomain/) removes it, and its routing ends at once: people in
it sign in hosted from then on, and SCIM can't provision people in it.

Source: https://docs.ezghcloud.com/sso/domains/index.mdx