feat(ui,clerk-js,shared): Add TXT domain verification to self-serve SSO

[LauraBeatris]

Description

Introduce a new step to create organization domains and verify them with TXT verification. This step is required before selecting a provider, and all domains must get verified before proceesing.

CleanShot.2026-06-12.at.17.12.48.mp4

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features

  • Add/manage organization SSO domains (add, list, remove) with strict domain validation, TXT ownership verification, bulk ownership verification flow, realtime polling until verified, and an Enterprise SSO badge.

• UX

  • SSO setup wizard now uses organization domains as the verification gate (skips verify step when all domains verified); Continue only when domains verified; domain suggestions when none exist.

• Localization

  • Updated domain-configuration copy across ~44 locales; pluralized “Verify domain” → “Verify domains”.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 15, 2026 9:57pm
swingset	Ready	Preview, Comment	Jun 15, 2026 9:57pm

[changeset-bot]

🦋 Changeset detected

Latest commit: d68eb75

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/localizations	Minor
@clerk/clerk-js	Minor
@clerk/shared	Minor
@clerk/ui	Minor
@clerk/react	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds TXT-based organization domain ownership verification: new DTOs and org APIs, cache keys and internal hook with polling, OrganizationDomainsStep UI and validators, ConfigureSSO/context rewiring to pass domain mutations, appearance/localization updates across locales, and updated tests.

Changes

Organization domain TXT verification

Layer / File(s)	Summary
Shared DTOs and localization types packages/shared/src/types/*	Adds ownership verification JSON types, extends OrganizationDomain JSON with affiliation/ownership fields, and updates LocalizationResource shape for organizationDomainsStep and enterprise SSO badge.
clerk-js resources packages/clerk-js/src/core/resources/*	Organization.getDomains supports enrollmentMode; createDomain accepts enrollmentMode; bulk prepare/attempt ownership verification endpoints added; OrganizationDomain parses affiliation and ownership verification payloads.
Stable keys & hook exports packages/shared/src/react/stable-keys.ts, packages/shared/src/react/hooks/index.ts, packages/shared/src/react/hooks/useOrganizationDomains.shared.ts	New ORGANIZATION_DOMAINS_KEY and useOrganizationDomains cache-key helper; re-exports internal useOrganizationDomains and its types.
useOrganizationDomains implementation packages/shared/src/react/hooks/useOrganizationDomains.tsx	Implements domain listing, createDomain (enterprise_sso path selects prepared verification), prepare/attempt ownership verification, revalidate, and polling of outstanding ownership verification attempts.
ConfigureSSO context & wiring packages/ui/src/components/ConfigureSSO/*, packages/ui/src/components/OrganizationProfile/*	Context and provider now carry enterpriseConnectionMutations and organizationDomainMutations; primary-email derived flows removed; ConfigureSSO/OrganizationSecurity pass organizationDomains and domain mutation handlers into the wizard.
OrganizationDomainsStep UI packages/ui/src/components/ConfigureSSO/steps/OrganizationDomainsStep.tsx	New wizard step with domain input, strict domain validator, suggestion from user email, domain cards showing TXT instructions/verified timestamp, create/delete flows, and Continue gating on ownershipVerification status.
Wizard & step updates packages/ui/src/components/ConfigureSSO/steps/*	Wizard now renders OrganizationDomainsStep for verification; SelectProvider forwards domain names to createConnection; VerifyDomainStep removed; various steps read mutations from enterpriseConnectionMutations.
Localization & appearance packages/localizations/src/*, packages/ui/src/customizables/*, packages/ui/src/internal/*	~40 locale files replace verifyEmailDomainStep with organizationDomainsStep; en-US adds enterprise SSO badge; new configureSSOVerifyDomain appearance keys and element selectors added.
Tests packages/ui/src/components/ConfigureSSO/__tests__/*, packages/ui/src/components/ConfigureSSO/steps/__tests__/*	Tests updated to mock organization domains, assert wizard navigation based on domain verification, adapt useConfigureSSO mock shape to enterpriseConnectionMutations, and verify domain-forwarding into createConnection.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• clerk/javascript#8799: Related ConfigureSSOWizard/step wiring changes.
• clerk/javascript#8796: Related OrganizationSecurity/ConfigureSSO page wiring and renaming work.

Suggested reviewers

• wobsoriano
• mauricioabreu

"🐰
I twitch my nose and dig the ground,
TXT records hum without a sound.
Domains hop in, proof tucked tight,
SSO leaps forward into light."

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8788

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8788

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8788

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8788

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8788

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8788

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8788

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8788

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8788

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8788

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8788

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8788

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8788

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8788

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8788

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8788

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8788

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8788

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8788

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8788

commit: d68eb75