# Verified domains

> Verify an organisation's email domains with a DNS TXT record before sign-in rules name them.

A verified domain is an email domain whose ownership the organisation has demonstrated with a DNS TXT record. LightHouse™ requires a verified domain before a sign-in rule can admit everyone at that domain.

## Requirements

| Requirement | Detail                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| Role        | `client_admin`, signed in as a person                                                                       |
| Access      | The ability to publish a TXT record in the domain’s DNS zone                                                |
| Domain      | Not a public mail domain (such as `gmail.com`; refused as `public_email_domain`) and not an Atlantic domain |
| Limit       | Up to 20 domains per tenant                                                                                 |

## Procedure

1. Open **Access → Domains**. Under **Add a domain**, enter the domain, such as `example.com`, and choose **Add domain**.

   Result: LightHouse shows the record to publish, and the domain is in the state **Waiting for the record**.

   | Type  | Name                                | Value                                    |
   | ----- | ----------------------------------- | ---------------------------------------- |
   | `TXT` | `_lighthouse-challenge.example.com` | `lighthouse-domain-verification=<token>` |

2. Publish the record at the DNS provider. The record is on its own label, `_lighthouse-challenge`; records at the domain apex, including MX and SPF, are unaffected. The token is public; its presence in the zone demonstrates control of the zone.

3. Choose **Check now**. LightHouse looks up the record over DNS-over-HTTPS through public resolvers. DNS changes can take up to an hour to propagate.

   Result: when the record is found, the domain is **Verified**. Sign-in rules may then name the domain and its subdomains.

## States

| State                      | Meaning                                                                                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Waiting for the record** | The domain has been added; the record has not been found                                                                                                                                                 |
| **Verified**               | The record was found. Sign-in rules may name the domain and its subdomains                                                                                                                               |
| **Record missing**         | The record was not found at the last daily check. The domain remains verified for 14 days, and the page shows the end date. Publish the record again to keep the domain verified                         |
| **Lapsed**                 | The record has been missing for more than 14 days. Saved rules continue to apply; the domain no longer counts as verified for new rules. Publish the record again and choose **Check now** to restore it |

LightHouse re-checks every verified domain once a day. A check that cannot be completed, for example because a resolver is unavailable, leaves the state unchanged, and the page reports that the check could not be made.

## Ownership by one tenant

A domain can be verified by one tenant only. A domain already verified by another organisation is refused; the refusal does not name that organisation. To dispute ownership, contact [Atlantic support](/operations/support/).

## Sign-in rules

| Case                                                                              | Behaviour                                                                                                             |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| New **Email domain** rule on the **Access** page                                  | Requires a verified domain or a subdomain of one; otherwise refused with `domain_not_verified`                        |
| Rule saved before domain verification was introduced                              | Continues to apply. The **Domains** page lists it as resting on an unverified domain, for the administrator to verify |
| Removing a domain that a rule relies on                                           | Refused with `domain_in_use` until the rule is changed or removed                                                     |
| [Single sign-on](/enterprise/single-sign-on/#turning-it-on) turned on for domains | Admits only verified domains                                                                                          |

## API

| Route                                 | Role                     | Action                                                                        |
| ------------------------------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `GET /api/v1/domains`                 | `client_admin`           | Lists the domains and their states                                            |
| `POST /api/v1/domains`                | `client_admin`, a person | Adds a domain, `{"domain": "example.com"}`, and returns the record to publish |
| `POST /api/v1/domains/{domain}/check` | `client_admin`, a person | Looks up the record                                                           |
| `DELETE /api/v1/domains/{domain}`     | `client_admin`, a person | Removes the domain                                                            |

The [API reference](/api/reference/) has the request and response shapes.

## Audit

Each change is recorded in the tenant’s audit log as `domain_added`, `domain_state_changed` or `domain_removed`, with the person who made it. A state change found by the daily re-check is recorded with the actor `aal:domains`.

Source: https://docs.atlanticagenticlabs.com/enterprise/domains/