---
id: UJ-001
title: Create an account, verify email, and sign in
actors: [new user, returning user]
surface: zync-www -> app.zync.is
goal: Obtain an authenticated tenant session.
trigger: User chooses sign up or sign in.
preconditions:
  - For sign up, email is not already registered.
success_state: Verified user has an active session and is routed to the correct tenant or onboarding.
source_specs:
  - docs/specs/2026-05-30-foundation-auth-rbac.md
  - docs/specs/2026-05-31-auth-2fa.md
  - docs/specs/2026-06-08-signup-csp-cors-fix-design.md
  - docs/specs/2026-05-31-zync-www-marketing-site.md
---

## Happy path

1. New user submits email, password, and name → Zync creates the global user, tenant, and initial `OWNER` membership, sends a verification email, and issues the signup session.
2. User opens the verification link → Zync marks `email_verified_at` and routes the user to onboarding.
3. Returning user submits credentials → Zync validates the account and creates the active tenant session.
4. If the user has multiple memberships, Zync presents the membership/tenant choice; otherwise it opens the only tenant.
5. User reaches the home/dashboard surface and can use only the permissions in the session.

## Alternate and failure paths

- Existing email, weak/invalid credentials, unverified email, suspended user, frozen membership, expired link, or rate limit → show a recoverable error and do not create an unauthorized session.
- User chooses forgot password → receives a time-limited reset flow, sets a new password, and signs in again.
- User has 2FA enrolled → completes phone OTP after password validation; wrong or expired OTP stops authentication.

## Permissions and boundaries

- Tenant authorization is membership + role + permission + subscription tier.
- System-admin sessions use the isolated admin surface and are not tenant sessions.

## Source specs

- `docs/specs/2026-05-30-foundation-auth-rbac.md`
- `docs/specs/2026-05-31-auth-2fa.md`
- `docs/specs/2026-06-08-signup-csp-cors-fix-design.md`
- `docs/specs/2026-05-31-zync-www-marketing-site.md`