# Organization Domains

Organization domains are available only in AISIX Cloud. An organization proves that it controls a DNS domain by publishing a TXT record. Once the domain is verified, the organization's identity provider (IdP) is trusted for email addresses in that domain: [single sign-on](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md) connects people to their accounts by email address without the Connect page, and [SCIM directory sync](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md) provisions them as members directly.

Every AISIX Cloud organization controls its own IdP and SCIM token, which could assert any email address, so AISIX Cloud trusts an address only after the organization proves that it owns the address's domain. AISIX Enterprise trusts its configured IdP for every address and therefore has no **Domains** page or domain endpoints.

## Who Can Manage Domains[​](#who-can-manage-domains "Direct link to Who Can Manage Domains")

Only an organization **owner** can add, verify, or remove domains, for the same reason that only an owner can configure SSO: whoever controls the trusted IdP can sign in as the accounts in a verified domain. The **Domains** page in the organization menu shows other roles an explanation only.

## Add and Verify a Domain[​](#add-and-verify-a-domain "Direct link to Add and Verify a Domain")

1. Open **Domains** in the organization menu.

2. Enter the domain, such as `example.com`, and select **Add domain**.

3. The page shows the TXT record to publish for the domain:

   | Type  | Name                           | Value                        |
   | ----- | ------------------------------ | ---------------------------- |
   | `TXT` | `_aisix-verification.<domain>` | `aisix-verification=<token>` |

   The token is generated when the domain is added. Copy the name and value with the **Copy** buttons.

4. Publish the record at the domain's DNS provider.

5. Back on the **Domains** page, select **Verify**. AISIX Cloud looks the record up at once. When it finds the value, the domain becomes **Verified**.

If the record is not found, the domain stays **Pending**, and you can select **Verify** again after the DNS change has propagated. If the DNS lookup itself fails, for example because it times out, the page reports the failure without treating the record as missing. Verification is rate-limited to 10 attempts per minute.

The rules for a domain name:

* Enter the bare domain name, such as `example.com`. It is stored in lowercase, without a trailing dot.
* Enter an internationalized domain name in its punycode form, starting with `xn--`.
* Public email domains, such as `gmail.com`, `outlook.com`, `qq.com`, and `163.com`, cannot be added.
* An organization can hold up to 50 domains, pending and verified together.

## Exact Match and Ownership[​](#exact-match-and-ownership "Direct link to Exact Match and Ownership")

A verified domain covers exactly that name and not its subdomains. Verifying `example.com` does not cover `mail.example.com`. Add and verify each domain that your email addresses use.

A verified domain belongs to one organization. Once an organization has verified a domain, no other organization can verify it. A pending domain reserves nothing, so several organizations can add the same domain, and the first one to verify it gets it.

## Re-Checks and Lapsing[​](#re-checks-and-lapsing "Direct link to Re-Checks and Lapsing")

AISIX Cloud checks every verified domain again about every 24 hours. When the record is missing or carries another value in 3 checks in a row, about 72 hours, the domain reverts to unverified and shows as **Lapsed**. Another organization can then verify it. The page shows how many checks in a row have failed. Select **Verify** at any time to check again, including for a lapsed domain.

A check whose DNS lookup fails, rather than finding no record, does not count as a failure. It is retried an hour later, so a resolver outage does not make domains lapse.

Keep the TXT record published for as long as the organization relies on the domain.

## What a Verified Domain Changes[​](#what-a-verified-domain-changes "Direct link to What a Verified Domain Changes")

For an email address in a verified domain:

* **SSO links accounts by email address.** On a person's first SSO sign-in, the account that uses the address is connected to their identity directly, without the [Connect page](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#the-connect-page). When no account uses the address, one is created if the organization admits the person, through just-in-time provisioning or an invitation. See [First Sign-In](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md#first-sign-in).
* **SCIM provisions members directly.** A user that SCIM provisions at the address becomes a member at once, on the account that uses the address, or on a new account without a password. Addresses outside the verified domains become [members waiting to join](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md#members-waiting-to-join) instead.
* **Unverified accounts are taken over.** An account that was registered for an address in the domain but never verified it is taken over when SSO or SCIM claims it. It loses its password, its sessions, its pending email verification links, and its links to other organizations' SSO connections. It is then reset to the account the organization would have created for the person: it takes the name that SSO or SCIM would have given a new account, the registrant's acceptance of the User Agreement and Privacy Policy is cleared, and its email address is marked verified. An account that already verified its address is only connected, and keeps its name.

Removing a domain, or a domain lapsing, does not disconnect anyone. Accounts already connected to the organization's SSO keep signing in. Only first sign-ins of new people go through the Connect page again.

Deleting the organization releases its domains at once, so another organization can verify them right away.

## Audit Records[​](#audit-records "Direct link to Audit Records")

Domain changes are recorded in the [audit log](https://docs.api7.ai/ai-gateway/cloud/logging-and-auditing.md) with the resource type `org_domain` and the actions `create`, `verify`, `lapse`, and `delete`. The entries name the domain, and a `lapse` entry also carries the number of failed checks. The verification token is never recorded.

Each takeover of an unverified account is recorded in the audit log of the organization whose domain took it over, with the resource type `verified_domain_claim`, the action `create`, and the account's ID as the resource ID. Its recorded after state carries:

| Field                        | Value                                                                |
| ---------------------------- | -------------------------------------------------------------------- |
| `via`                        | `sso` for a single sign-on, or `scim` for directory sync.            |
| `domain`                     | The verified domain of the address.                                  |
| `user_id`                    | The account's ID.                                                    |
| `previous_name`              | The account's name before the takeover.                              |
| `password_revoked`           | `true` when the account had a password that was removed.             |
| `sessions_revoked`           | The number of sessions ended.                                        |
| `verification_links_revoked` | The number of pending email verification links retired.              |
| `identity_links_removed`     | The number of links to other organizations' SSO connections removed. |

For a single sign-on, the actor is the account itself, as on other SSO entries. For directory sync, the actor is the owner of the SCIM token. Each removed SSO link is also recorded in the log of the organization it belonged to, as an `sso_identity_link` deletion.

## Next Steps[​](#next-steps "Direct link to Next Steps")

Configure [Single Sign-On (SAML)](https://docs.api7.ai/ai-gateway/cloud/single-sign-on.md) and [SCIM Directory Sync](https://docs.api7.ai/ai-gateway/cloud/scim-directory-sync.md) for the people in your verified domains.
