Domains
This page is for the owners and admins who prove that an organization controls a domain, such as acme.com. You will add the domain, publish a DNS TXT record, verify it, and keep it verified.
A verified domain belongs to one organization only. Two features rely on it: routing your people's sign-in to your company's identity provider, and the Verified badge on your organization's apps. The proof is the same for both. You make it once, under Developer ▸ Domains.
Before you start
- Who can do this: an owner or an admin of the organization adds, verifies and removes domains. Every member can see them. Removing a domain that routes sign-ins is an owner's job.
- Plan: adding and verifying domains isn't limited by plan. An organization keeps at most 20 domains, verified or not.
- What you need: access to the domain's DNS zone, to add a TXT record. In the editor, turn on Developer mode (Settings ▸ General ▸ For developers ▸ Developer mode) to see Developer in the side bar.
Add a domain and verify it
Open Developer ▸ Domains
The page lists Your domains, or says No domains yet.
Add the domain
Under Add a domain, type it in Domain, such as
acme.comorapp.acme.com, and choose Add. You can pasteAcme.com,https://acme.com/or@acme.com: the server keepsacme.com. The domain shows as Waiting, with its TXT record.Publish the TXT record at your DNS provider
Copy the Name (host) and the Value into a new TXT record. The name is
_instruction-md-challenge.and your domain. The value starts withinstruction-md-verification=, followed by a random part that is the same for as long as the domain stays added.Choose Check now
The server looks the record up at once. When it holds your value, the domain shows Verified. Otherwise it shows Not verified yet, with the reason. DNS changes can take a few minutes to appear.
As a zone file line, the record looks like this:
_instruction-md-challenge.acme.com. 3600 IN TXT "instruction-md-verification=Zk3pQ0v8sJ2mW7rT1yB4nC6xD9eF5gH0" A record may be split into several strings, as long TXT values often are. The check joins each record's strings before it compares them. Other TXT records at the same name don't matter.
Do it with the MCP server
The editor calls these tools. They need a token with the org:admin scope (org:admin). orgs_domains_list is a read tool any member may call; the other three are admin-class, so the server offers them to people only, never to an agent's or a service's token. There is no CLI command for domains.
The older orgs_signin_domains_add, orgs_signin_domains_verify and orgs_signin_domains_remove work on the same list with the same record, but adding and verifying through them needs a plan that includes single sign-on. Their answers don't say what uses each domain. The orgs_domains_* tools are the ones to use.
| Tool | What it does | Arguments |
|---|---|---|
orgs_domains_list | List your domains | orgId |
orgs_domains_add | Add a domain | orgId, idempotencyKey (optional), domain |
orgs_domains_verify | Verify a domain | orgId, domain |
orgs_domains_remove | Remove a domain (can ask first) | orgId, confirmToken (optional), domain |
Add the domain. The answer lists every domain of the organization, each with the record it needs:
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "domain": "acme.com" } {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"domains": [
{
"domain": "acme.com",
"verified": false,
"verifiedAt": null,
"checkedAt": null,
"lastError": null,
"record": {
"type": "TXT",
"name": "_instruction-md-challenge.acme.com",
"value": "instruction-md-verification=Zk3pQ0v8sJ2mW7rT1yB4nC6xD9eF5gH0"
},
"usedBy": { "signIn": false, "apps": 0 }
}
]
} Adding a domain the organization already has changes nothing and answers the same list. With idempotencyKey, the same call sent again answers its first result.
Verify it once the record is published:
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "domain": "acme.com" } {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"domains": [ … ],
"verified": false,
"reason": "no TXT record at _instruction-md-challenge.acme.com yet"
} {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
"domains": [
{
"domain": "acme.com",
"verified": true,
"verifiedAt": "2026-11-22T09:14:03.512Z",
"checkedAt": "2026-11-22T09:14:03.512Z",
"lastError": null,
"record": { "type": "TXT", "name": "_instruction-md-challenge.acme.com", "value": "instruction-md-verification=Zk3pQ0v8sJ2mW7rT1yB4nC6xD9eF5gH0" },
"usedBy": { "signIn": false, "apps": 0 }
}
],
"verified": true
} A failed check is not an error: the answer has verified: false and a reason, and the domain's lastError keeps it. checkedAt is the last lookup. usedBy.signIn is true while the domain routes sign-ins, and usedBy.apps counts the apps whose Verified badge it gives.
Keep it verified
Keep the record for as long as you want the domain. A verified domain is looked up again about every 60 minutes.
- A lookup that finds your value resets the count of misses.
- A lookup that finds no record, or a record without your value, is a miss. After 3 misses in a row the domain is no longer verified. With a lookup every 60 minutes, that is about 3 hours after the record went. A DNS change in flight, or a short outage at your DNS provider, survives.
- A lookup that fails on its own (a resolver error or a timeout) says nothing about the record. It is noted in
lastErrorand not counted.
When a domain is no longer verified, the organization's activity records "The domain … is no longer verified: its DNS record was missing … times in a row", and every owner gets a notification. It stops routing sign-ins, and apps whose redirects are on it turn off. Publish the record again and choose Check now to verify it again.
You can check the record yourself:
dig +short TXT _instruction-md-challenge.acme.com "instruction-md-verification=Zk3pQ0v8sJ2mW7rT1yB4nC6xD9eF5gH0" Domains that are refused
- Public mail services. Anyone can have an address there, so no organization can own one. The list, from the code:
The 62 refused mail domains
gmail.com, googlemail.com, google.com, outlook.com, hotmail.com, hotmail.co.uk, live.com, msn.com, microsoft.com, yahoo.com, yahoo.co.uk, yahoo.fr, yahoo.de, ymail.com, rocketmail.com, aol.com, icloud.com, me.com, mac.com, proton.me, protonmail.com, pm.me, gmx.com, gmx.de, gmx.net, web.de, mail.com, yandex.com, yandex.ru, mail.ru, zoho.com, zohomail.com, fastmail.com, fastmail.fm, tutanota.com, tuta.io, hey.com, qq.com, 163.com, 126.com, naver.com, daum.net, seznam.cz, wp.pl, o2.pl, libero.it, orange.fr, free.fr, laposte.net, btinternet.com, comcast.net, verizon.net, att.net, sbcglobal.net, rediffmail.com, inbox.com, duck.com, skiff.com, hushmail.com, example.com, example.org, example.net- instruction.md's own:
instruction.mdandtsok.org, and every name under them. - Another organization's. A domain another organization has verified can't be added. Two organizations can add the same domain while neither has verified it; the first to verify it has it, and the other's check is refused.
- Not a domain. An IP address, a single label (
acme), or a name whose last label is all digits.
What depends on a domain
| Feature | What the domain does | When it stops being verified or is removed |
|---|---|---|
| Sign-in through your identity provider | Someone who types an address at a verified domain on the sign-in page is sent to your identity provider. Only addresses at your verified domains can sign in through it. | They aren't sent there any more. If single sign-on was required, it isn't required for them. Their accounts stay. |
| Your apps' Verified badge | An app whose address is on a verified domain shows Verified: acme.com, and its redirects may use the domain. | The app loses the badge, and turns off where a redirect is on the domain. |
A domain added for one feature serves the other: the editor's Developer ▸ Single sign-on page reads the same list.
Remove a domain
Choose Remove on the domain in Developer ▸ Domains, then Remove again under Remove acme.com?. Or call orgs_domains_remove. You can add it again later, with a new record value.
Through the MCP server, a domain nothing uses goes at once. One that routes sign-ins, or that an app's badge or redirects need, asks first. The question names what changes, such as "Its people aren't sent to Okta any more." In the MCP server this is the needs_confirmation answer: show it to the person, and send the same call again with its confirmToken only if they agree (Needs confirmation). Only an owner can remove a domain that routes sign-ins; an admin gets forbidden.
Every add, first verification and removal is in the organization's activity. A first verification notifies every owner, and so does the removal of a domain that routed sign-ins or gave an app its badge.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
that isn't an email domain: write it as acme.com |
The text isn't a domain name. | Type the domain only, without a path or a port. |
… is a public mail service: anyone can have an address there, so it can't be your organization's |
It is on the list above. | Use your company's own domain. |
… can't be claimed here |
It is instruction.md's. | Use your own domain. |
… is verified by another organization (conflict) |
Another organization proved it first. | Ask that organization to remove it, or write to us. |
an organization has at most … domains (limit_reached) |
The organization has 20. | Remove one you don't use. |
no TXT record at … yet |
The record isn't published, isn't visible yet, or is at another name. | Check the name: some DNS providers add your domain to it themselves, so type only _instruction-md-challenge. Wait a few minutes and check again. |
the TXT record at … doesn't hold this organization's value |
A record is there with another value, such as one from before the domain was removed and added again. | Replace the value with the one the page shows now. |
the lookup of … failed (…); try again in a few minutes |
The DNS lookup itself failed. | Try again later. Such a failure never counts against a verified domain. |
| Still stuck | Report it with the domain and the message. |
Questions
Can I verify a subdomain only?
Yes. Add app.acme.com and publish the record at _instruction-md-challenge.app.acme.com. A verified subdomain doesn't verify its parent, and the parent doesn't verify its subdomains: each is added on its own.
Can I delete the TXT record once the domain is verified?
No. A verified domain is looked up again about every 60 minutes, and 3 misses in a row unverify it. Keep the record for as long as you keep the domain.
Does a domain need the Enterprise plan?
No. Adding and verifying a domain isn't limited by plan. Sign-in through your identity provider is a plan feature of its own; the domain is only its proof.
Is the record's value secret?
No. It is published in public DNS. It only proves that whoever controls the zone chose to publish this organization's value. Removing the domain and adding it again gives it a new value.