> ## Documentation Index > Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt > Use this file to discover all available pages before exploring further. # Verifying a Domain for SSO > Prove control of your email domain with a DNS TXT record before your identity provider can assert accounts at it. The exact record, the rules, and every refusal. # Verifying a Domain for SSO Your identity provider signs its own assertions. Nothing in SAML stops it asserting `ceo@some-other-company.com` — the signature proves the message came from your IdP, not that your IdP speaks for that address. KnoxCall therefore admits an assertion only for domains the workspace has **proven** it controls, by publishing a DNS TXT record. Until at least one domain is proven, SAML sign-in cannot create or link any account for the workspace: just-in-time provisioning is refused outright, and a pre-existing account that is not already a member is refused too. ## The record Claim the domain in KnoxCall first — the value contains a token minted for your workspace, so there is nothing to publish until you have it. | | | | --------- | -------------------------------------- | | **Name** | `_knoxcall-verify.acme.com` | | **Type** | `TXT` | | **Value** | `knoxcall-domain-verification=` | The name is the label `_knoxcall-verify` **beneath the domain you are proving** — proving `eu.acme.com` means publishing at `_knoxcall-verify.eu.acme.com`. The value must match exactly, including the `knoxcall-domain-verification=` prefix; a provider that splits long TXT strings into chunks is fine, KnoxCall re-joins them before comparing. ## Adding and verifying a domain **Settings → Single sign-on**, open the connection, then the **Domains** tab. 1. Type the domain and press **Claim domain**. The row appears straight away, marked *Waiting for the TXT record*, carrying the three values to publish — **Record name**, **Record type** and **Record value** — each with a copy button. 2. Publish that TXT record in your DNS, and give it time to propagate. 3. Press **Verify**. KnoxCall resolves the name and compares the value. On success the row becomes *Proven*, with the date. On failure the claim stays exactly where it was and the row shows what the check actually saw, under *Last check reported* — fix the record and press **Verify** again. **Remove** deletes a claim or a proof. Removing a proof stops it admitting logins at the very next sign-in. A domain proven on that tab admits **every** connection in the workspace. (KnoxCall can also honour a proof bound to a single connection, but nothing creates one yet, so every proof you make today is workspace-wide.) Re-claiming a domain you have already claimed returns the **same** token rather than rotating it, so reloading the page, or retrying, never invalidates a record you have already published. ### The same thing from a script The tab is the supported flow; these are the routes underneath it, if you provision workspaces from code. They need an authenticated dashboard session belonging to an **owner or admin** who has re-authenticated in the last 5 minutes. ```http theme={"dark"} POST /admin/saml/domains { "domain": "acme.com" } ``` The response carries the record to publish. Publish it, wait for DNS to propagate, then: ```http theme={"dark"} POST /admin/saml/domains//verify ``` `GET /admin/saml/domains` lists what you have claimed and proven; `DELETE /admin/saml/domains/` removes a claim or a proof. ## What a proven domain covers * **Exactly the domain, and anything beneath it.** Proving `acme.com` admits `alice@acme.com` and `bob@eu.acme.com`. * **Never a parent.** Proving `eu.acme.com` does not admit `alice@acme.com`. That direction is the one an attacker would want. * **Proof is read live, on every assertion.** Removing a proof stops it admitting logins at the next sign-in — there is no cached grant to expire. You can also narrow admission further with the connection's **verified email domains** list. That list is a filter over your proven domains, not an authority of its own: putting a domain in it that you have not proven is refused, and a domain on it whose proof you later delete admits nobody at the very next sign-in. The settings form requires at least one entry; a connection carrying none admits every domain you have proven. **A domain verified for sending mail does not admit an SSO login.** They are two proofs about two different questions, and since 8 September 2026 `tenant_sso_domains` — the table this page writes — is the only authority KnoxCall consults when deciding whose IdP-asserted address may claim a KnoxCall account. Mail verification is written by an onboarding flow and by an unattended job, and its rules were written for undelivered mail, not for account takeover. If you verified a domain for email, verify it again here: the same style of TXT record, under a different name, and it takes a minute. Nothing broke at the changeover — every mail-verified domain that a configured SSO connection was relying on was carried across once. New domains are proven here only. ## Rules a domain has to satisfy | Rule | Why | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A real, public domain | *"Enter a full domain, for example acme.com — a single label cannot be proven."* Reserved names (`.local`, `.internal`, `example.com`, and the rest of RFC 2606/6761) are refused: nobody can hold them on the public internet, so control of them cannot be proven. | | Not a shared mailbox provider | *"`gmail.com` is a shared mailbox provider. Proving it would let this tenant claim any account at that domain, so it can never be used for single sign-on. Use a domain your company controls."* | | Not a KnoxCall domain | Proving one would let a workspace claim KnoxCall staff accounts. | | Not an IP address | An address is not a domain. | | Not already **proven** by another workspace | Competing *unverified* claims are allowed — the race is decided at verification, not at claim time, so nobody can squat a domain by typing it into a trial account. | ## When verification fails Each of these leaves the claim in place; fix the cause and verify again. | Message | What happened | What to do | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *"No TXT record was found at `_knoxcall-verify.acme.com`. DNS changes can take a few minutes to propagate — publish the record and try again."* | Nothing resolves at that name yet. | Check the record name — many DNS UIs append the zone for you, so entering the full name can produce `_knoxcall-verify.acme.com.acme.com`. Then wait out the TTL. | | *"The TXT record at `_knoxcall-verify.acme.com` does not contain this account's verification value…"* | A TXT record exists, but not ours. | Copy the value again, including the `knoxcall-domain-verification=` prefix and with no surrounding quotes added by the DNS editor. | | *"That domain could not be verified for this account. If you control it and this is unexpected, contact support with the domain name and we will look into it."* | Another workspace already holds a **verified** proof for this domain. | Contact support. The message is deliberately uninformative — it must not report which other customer holds a domain. | | *"`acme.com` is a reserved name that nobody can hold on the public internet…"* / *"…is a shared mailbox provider…"* | The domain can never be proven. | Use a domain your company controls in public DNS. | ## Two refusals you will meet on the connection, not the domain * *"At least one verified email domain is required. Without it, SAML sign-in cannot create or link any account for this tenant — just-in-time provisioning is refused outright, and a pre-existing account that is not already a member is refused too."* — you saved a connection with an empty domain list. * *"`eu.acme.com` is not covered by a domain you have verified for single sign-on (`acme-corp.com`). A SAML assertion is signed by your own IdP, so KnoxCall only lets it claim addresses at domains you have proven you control under Settings → Single sign-on → Domains."* — the list names a domain whose proof does not cover it. Prove that domain on the **Domains** tab, or list one that is covered. * *"You have not verified any domain for single sign-on yet, so `acme.com` cannot be trusted for SAML sign-in. … A domain verified for sending mail is a separate proof and does not count here…"* — you have proven nothing under **Single sign-on → Domains**. Do that first; a mail-sending proof is not accepted here (see the note above). Next: pick your provider — [Microsoft Entra ID](/sso/entra-id), [Okta](/sso/okta), [Google Workspace](/sso/google-workspace) or [JumpCloud](/sso/jumpcloud).