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

  1. Open Developer ▸ Domains

    The page lists Your domains, or says No domains yet.

  2. Add the domain

    Under Add a domain, type it in Domain, such as acme.com or app.acme.com, and choose Add. You can paste Acme.com, https://acme.com/ or @acme.com: the server keeps acme.com. The domain shows as Waiting, with its TXT record.

  3. 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 with instruction-md-verification=, followed by a random part that is the same for as long as the domain stays added.

  4. 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.

Publish this TXT record, then choose Check now.

As a zone file line, the record looks like this:

The TXT record
_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.

ToolWhat it doesArguments
orgs_domains_listList your domainsorgId
orgs_domains_addAdd a domainorgId, idempotencyKey (optional), domain
orgs_domains_verifyVerify a domainorgId, domain
orgs_domains_removeRemove 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:

orgs_domains_add arguments
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "domain": "acme.com" }
The answer
{
  "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:

orgs_domains_verify arguments
{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C", "domain": "acme.com" }
Before the record is there
{
  "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2C",
  "domains": [ … ],
  "verified": false,
  "reason": "no TXT record at _instruction-md-challenge.acme.com yet"
}
Once it holds your value
{
  "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 lastError and 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:

Look the record up
dig +short TXT _instruction-md-challenge.acme.com
Output
"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 domainsgmail.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.md and tsok.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.

Last checked against the product:

Was this page helpful? Report a problem