Concepts
Organization domain verification
Domain routing is what lets somebody type a work email and land at their own company's identity provider without choosing anything. It works because a domain belongs to exactly one organization — and that only stays true if claiming a domain requires proving you control it.
Why a claim is not enough
Domain routing turns an email address into a tenant. Somebody types avery@foo-corp.example, the domain resolves to one organization, and the browser is redirected to that organization's connection. It is the least friction any enterprise sign-in can have, and it depends entirely on the mapping being trustworthy.
If claiming a domain were sufficient, anyone who could create an organization could claim a domain they do not own and intercept sign-ins for it. That is not a subtle attack; it is the whole system inverted. So a claimed domain sits in a pending state, is recorded but ignored for routing, and starts routing only once control has been demonstrated.
The demonstration is publishing a DNS TXT record. It is not the only mechanism that would work, but it is the one every IT team already knows how to do, and it proves the specific thing that matters: whoever set this up controls the domain's DNS, which is the same authority that controls its mail.
The states a domain moves through
| State | Routes sign-ins | What is happening |
|---|---|---|
| pending | No | The domain is claimed and a verification token has been issued. Nothing routes yet. |
| verified | Yes | The TXT record was found. The domain now resolves to this organization. |
| failed | No | Verification was attempted and the record was absent or wrong. Retryable. |
A domain in pending is not an error and does not need to be cleared. Customers routinely claim a domain during setup and publish the record a week later, when whoever administers DNS gets to the ticket.
Verifying a domain
The flow below is what the customer's IT team does, usually inside the Admin Portal rather than by talking to you. Where you are doing it on their behalf, the same steps apply through the API.
- 1Add the domain to the organization. It is created in pending, with a verification token in the response.
- 2Publish the token as a TXT record on the domain. The record name and value are both shown in the portal; both must match exactly.
- 3Wait for DNS to propagate. This is usually minutes and occasionally hours, depending on the previous record's time to live.
- 4Trigger verification, or let the scheduled check find it. On success the state becomes verified and routing begins immediately.
- 5Leave the record in place. It is checked periodically, and removing it eventually returns the domain to an unverified state.
1# 1. Alan adi eklenir — dogrulama jetonu doner.2curl -X PUT https://api.paycux.com/organizations/org_01HQ8ZK3M4N5P6R7S8T9V0W1X2 \3 -H "Authorization: Bearer sk_example_123456789" \4 -H "Content-Type: application/json" \5 -d '{ "domain_data": [{ "domain": "foo-corp.example", "state": "pending" }] }'67# 2. TXT kaydi yayinlanir.8# foo-corp.example. TXT "paycux-domain-verification=8f2c41ab"910# 3. Yayildigi dogrulanir.11dig +short TXT foo-corp.example
Subdomains, multiple domains and consumer addresses
Verification applies to the exact domain claimed. Verifying foo-corp.example does not verify eu.foo-corp.example — deliberately, because subdomains are frequently delegated to a different team or a different company entirely, and inheriting trust downwards would let a delegated subdomain be claimed by whoever holds it.
Large customers routinely own several domains, often as a result of acquisitions, and expect all of them to reach the same tenant. Add each one to the same organization and verify each separately; routing then resolves any of them to the same place.
Public consumer mail domains cannot be claimed at all. If a customer genuinely signs in with consumer addresses — small firms and sole traders do — route them with a workspace slug or an explicit organization picker rather than by domain. This is a product decision, not a limitation to work around.
A domain already verified by another organization cannot be claimed; the API returns 422 naming the conflict rather than moving it. This is the correct behaviour and occasionally surprises somebody who created a test organization months ago with a domain they now want for the real one.
Using verified domains to route a sign-in
Once a domain is verified, the lookup is one call. The important detail is what happens when it finds nothing: most people signing in to most products are not enterprise users, so an empty result is the normal case and must fall through to your ordinary sign-in rather than producing an error.
1const domain = email.split("@")[1];2const { data } = await paycux.organizations.list({ domains: [domain] });3const organization = data[0];45if (!organization) {6 // Cogu kullanici icin normal durum — hata degil.7 return Response.json({ sso: false });8}910const url = paycux.sso.getAuthorizationUrl({11 clientId: process.env.PAYCUX_CLIENT_ID,12 redirectUri: process.env.PAYCUX_REDIRECT_URI,13 organizationId: organization.id,14});1516return Response.json({ sso: true, url });