Add and verify a domain · BreezeAuth Docs

This page walks you through adding a domain to your organization and verifying it. You will need about ten minutes and access to the domain’s DNS settings, or the help of the person who has it.

Before you start

Permissions. You need the Owner or Administrator role. If the Domains tab is greyed out, or you don’t see the Add domain button, ask an administrator of your organization.
Access to the domain’s DNS. Verification requires adding a TXT record to the domain. This is done in the control panel of the company that hosts the domain’s DNS, not in BreezeAuth.

Find the domains of your organization

Sign in to the admin console.
In the sidebar, select Organization. The Manage Organization page opens.
Select the Domains tab.

The list shows every domain added to the organization, when it was added and its status: Verified, with the verification date, or Pending.

Tip: while your organization has no verified domain, the admin console reminds administrators with the Verify a domain to unlock managed users dialog. Select Verify a domain to go straight to this tab, or Not now to hide it until your next session.

Add a domain

On the Domains tab, select Add domain. The Add a new domain dialog opens.
In Domain, enter the domain only, without https://, www. or an e-mail address. For example: example.com.
Select Confirm.

The domain is added as Pending, and the Verify domain dialog opens with the DNS record to publish.

A few rules apply:

The domain must be a full domain name, such as example.com or example.com.br. Letters, numbers, hyphens and dots are allowed. Uppercase letters are converted to lowercase.
Add the domain exactly as it appears after the @ in e-mail addresses. If some people use @sales.example.com, add sales.example.com as a separate domain.
If you see This domain has already been added to this organization., the domain is already in the list.
If you see This domain is already verified for another organization., another BreezeAuth organization has already proven ownership of it. If you believe this is a mistake, contact support.

Publish the DNS record

The Verify domain dialog shows the record to add to the domain’s DNS:

Field	What to enter
Record type	`TXT`
Name / Host	`@` or blank, meaning the domain itself. Some providers ask you to type the full domain instead.
Value	The value shown in the dialog, such as `breeze-auth-domain-verification=6f1c…`. Use the copy button next to it.

Select the copy button next to Value.
In another browser tab, open the DNS settings of your domain at your DNS provider.
Create a new record of type TXT for the domain itself (@) and paste the value.
Save the record.

If you can’t change the DNS yourself, send the three values above to the person who manages your domain. You can close the dialog and come back later: the value stays the same and is shown again when you select Verify domain.

Note: adding a TXT record doesn’t affect your website or e-mail. A domain can have many TXT records, for example for e-mail security (SPF) or other services. Don’t edit or remove existing ones, just add a new one.

Start the verification

On the Domains tab, select Verify domain next to the pending domain, if the dialog isn’t open already.
Select Start verification.
Wait a few seconds while BreezeAuth checks the domain’s DNS.

If the record is found, you see Domain verified successfully. and the domain is shown as Verified. BreezeAuth then converts the accounts on the domain into managed users in the background. See What happens to existing accounts.

If you see Could not verify the domain, the record wasn’t found yet. The domain stays Pending and you can try again at any time.

Important: DNS changes take time to spread across the internet. It usually takes a few minutes, but depending on your DNS provider it can take several hours. Verification fails until then. BreezeAuth doesn’t retry automatically: select Start verification again later.

If verification keeps failing

Check	What to do
The record is on the wrong name	The record must be on the domain itself (`@`), not on a subdomain such as `www`. Some providers add the domain automatically, turning `example.com` into `example.com.example.com`.
The value is incomplete	Paste the full value, including the `breeze-auth-domain-verification=` prefix, with no extra spaces or quotes added by hand.
The record is on the wrong domain	Make sure you edited the DNS zone of the same domain you added in BreezeAuth.
The DNS change hasn’t propagated yet	Wait a little and try again. Your IT team can check what the internet sees with a tool such as `nslookup -type=TXT example.com` or an online DNS lookup service.
The domain uses another DNS provider	If you recently moved your domain, the record must be added at the provider that currently answers for the domain (its “name servers”).

After verification

Keep the record. BreezeAuth checks the record only when you start the verification, so removing it later doesn’t undo it. We still recommend keeping it, so that anyone looking at your DNS knows why it is there.
Verify your other domains. Repeat these steps for every domain your people’s e-mail addresses use.
Review existing accounts. Some people may now appear as Pending review under Users. See Review pending accounts.

Delete a domain

On the Domains tab, select the trash icon next to the domain.
Confirm in the Delete domain dialog.

Important: deleting a domain cannot be undone. If you add it again later, BreezeAuth generates a new value and you need to update the DNS record and verify it again.

When you delete a verified domain:

Accounts that are already managed by your organization stay managed. They are not converted back to guests.
People you add from then on with an e-mail on that domain are invited as guests.
Anyone can again create a personal BreezeAuth account with an e-mail on that domain, and another organization can add and verify it.

Deleting a pending domain has no effect on any account.

Changes are audited

Adding, verifying and deleting domains are recorded in your organization’s Audit Logs, together with who made the change and when. If your systems need to react to these changes, subscribe a webhook to the domain events.