Auto-associate new users to an existing workspace by email domain #105
Description
☑️ Problem / User Need
New teammates often spin up duplicate workspaces or ping support for an invite.
This friction slows adoption and drives up churn.
Goal
If someone signs up with a company-owned email domain (e.g. @kodus.io), detect the existing workspace and give them a one-click path to join it.
✅ Acceptance Criteria
| Area | Requirement |
|---|---|
| Create Workspace screen | The “Create a Workspace” step now contains: • Allowed Domains InputTag — comma/Enter creates chips.• For non-public domains ( gmail.com, outlook.com, …) pre-populate the domain.• Checkbox under the input: “Allow new users from this domain to join automatically.” (checked by default). • Validation: – If the checkbox is checked and the list is empty ⇒ inline error “Add at least one domain or disable auto-join.” – All domains must match ^[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$.• Unchecking the box keeps the domain list but saves autoJoinEnabled = false. |
| Join-or-Create screen | Replace the old modal with a dedicated route /signup/join-or-create that reuses the same AuthCard wrapper as other signup steps.H1: “You’re part of {OrgName}”P: “Join your team’s existing workspace or create a new one:”Primary CTA → Join existing workspace. Secondary CTA → Create new workspace. Back link returns to previous step. Route guard: only accessible when matchedOrgId is provided by the Auth service. |
| Organization settings | Path: Avatar → Workspace → Settings → Access control. Admins can edit Allowed domains and toggle Auto-join; changes apply immediately. |
| Backend | Extend Organization with:• allowedDomains: string[]• autoJoinEnabled: booleanMigration + CRUD in both creation and settings endpoints. |
| Signup flow (server) | On UserCreated, look up orgs where autoJoinEnabled = true and email domain ∈ allowedDomains; return matchedOrgId (fallback to normal flow when none found). |
| Fail-safe | If no match is found, user goes through the standard workspace-creation flow. |
💡 Implementation Notes
| Layer | Hint |
|---|---|
| Front-end | Reuse AuthCard; checkbox is <Checkbox id="autoJoin" defaultChecked /> with aria-controls tied to domain input. |
| API / DB | Add columns, validation; PATCH /org/:id/access-control. |
| Auth service | Lookup by domain on UserCreated. |
| Telemetry | Events: workspace_create_domains_autofill, workspace_join_screen_viewed, workspace_join_clicked, workspace_create_clicked. |
| UX copy | Keep Kodus tone; avoid jargon like “tenant.” |
Edge Cases
- Multiple company domains (
kodus.io,kodus.dev, …). - Public + private domains mixed.
- Admin removes a domain with active members.
- Two orgs claim the same domain (first-come-first-served or manual resolution).
📣 Additional Context
Enterprise pilots ask for zero-friction onboarding for 50–100 seats. Support receives frequent “How do I join my company workspace?” tickets. Editable settings let admins tighten or loosen access as their domain strategy evolves.
🖼️ References
