ATLAS
Customer Magic Link

Public magic link onboarding — 7-state flow from contractor invite through claim to active customer. Source: app/(public)/join/[token].tsx

1 Loading
2 Ready
3 Claiming
4 Success
5 Existing
6 Expired
7 Error
1. Loading Live
PageState: loading — fetching invite info from API
9:41
Join 3bids
Loading invite...
2. Ready — Accept Invite Live
PageState: ready — invite fetched, user can claim
9:41
Join 3bids
You’re Invited!
Cole Construction has invited you to join 3bids.
Get competitive bids on home projects
Verified, licensed contractors
Secure payments & escrow protection
Expires April 1, 2026
3. Claiming Live
PageState: claiming — setting up account
9:41
Join 3bids
Setting up your account...
4a. Success — New Account Live
PageState: success (isNewAccount: true)
9:41
Join 3bids
You’re In!
Your 3bids account has been created. Check your email for login instructions.
What’s Next?
Check your email for login details
Download the 3bids app
Post your first project
4b. Success — Existing Linked Live
PageState: success (isNewAccount: false)
9:41
Join 3bids
You’re In!
Your account has been linked. You can now access 3bids.
What’s Next?
Check your email for login details
Download the 3bids app
Post your first project
5. Existing Account — Sign In Required Live
PageState: existing_account — user already registered, needs to sign in to link contractor
9:41
Join 3bids
Account Already Exists
You already have a 3bids account. Sign in to link this contractor to your account.
Once signed in, you’ll be automatically linked to this contractor.
6. Expired Live
PageState: expired — invite link has expired (7-day window)
9:41
Join 3bids
Invite Expired
This invite link has expired. Please ask the contractor to send you a new invitation.
7a. Error — Invalid Token Live
PageState: error (invalid_token)
9:41
Join 3bids
Invalid Invite
This invite link is no longer valid.
7b. Error — Network Live
PageState: error (network_error)
9:41
Join 3bids
Invalid Invite
Unable to connect. Please check your internet connection.
7c. Error — Missing Token Live
PageState: error (missing_token)
9:41
Join 3bids
Invalid Invite
No invite token was provided.
1 Loading
2 Ready
3 Success
4 Existing
5 Expired
6 Error
Loading Live
9:41
Join 3bids
Loading invite...
Ready — Accept Invite Live
9:41
Join 3bids
You’re Invited!
From Cole Construction
Expires April 1, 2026
Why Join 3bids?
Get competitive bids on home projects
Verified, licensed contractors
Secure payments & escrow protection
Passwordless AccessMagic links provide secure, frictionless onboarding. No passwords needed.
Success — Account Created Live
9:41
Join 3bids
You’re In!
Account created successfully
What’s Next?
Check your email for login details
Download the 3bids app
Post your first project
Existing Account — Sign In Live
9:41
Join 3bids
Account Exists
Sign in to link this contractor
You already have a 3bids account. Sign in to link this contractor to your account.
Once signed in, you’ll be automatically linked to this contractor.
Expired Live
9:41
Join 3bids
Invite Expired
This invite link has expired. Please ask the contractor to send you a new invitation.
Error States Live
9:41
Join 3bids
Invalid Invite
This invite link is no longer valid.
1 Loading
2 Ready
3 Success
4 Existing
5 Expired
6 Error
Loading Live
https://app.3bids.io/join/abc123xyz
Loading invite...
Ready — Accept Invite Live
https://app.3bids.io/join/abc123xyz
You’re Invited!
Cole Construction has invited you to join 3bids.
Competitive Bids
Get multiple bids on home projects
Verified Contractors
Licensed & insured professionals
Escrow Protection
Secure payments held in escrow
Expires April 1, 2026
Success — Account Created Live
https://app.3bids.io/join/abc123xyz
You’re In!
Your 3bids account has been created. Check your email for login instructions.
What’s Next?
Check your email for login details
Download the 3bids app
Post your first project
Existing Account — Sign In Live
https://app.3bids.io/join/abc123xyz
Account Already Exists
You already have a 3bids account. Sign in to link this contractor to your account.
Once signed in, you’ll be automatically linked to this contractor.
Expired Live
https://app.3bids.io/join/expired-token
Invite Expired
This invite link has expired. Please ask the contractor to send you a new invitation.
Error — Invalid Token Live
https://app.3bids.io/join/bad-token
Invalid Invite
This invite link is no longer valid.

Data Architecture

Customer magic link onboarding — 7-state public claim flow from invite token to active customer account. Handles new users (Case A), shadow users (Case B), and existing registered users (Case C).

Source Files

app/(public)/join/[token].tsx
Public magic link landing page — 7-state PageState machine (loading, error, expired, ready, claiming, success, existing_account)
Component
app/(public)/_layout.tsx
Public routes layout with Stack navigator, no auth required
Component
convex/intake/magicLink.ts
Backend magic link system — SHA-256 hashed tokens, 7-day expiration, progress tracking
Backend

HTTP API Endpoints

GET /v1/customer/invite?token=
Validate token, return contractor info, customer email, and expiration. Returns 410 if expired.
Query
POST /v1/customer/invite/claim
Claim invite — creates shadow account (Case A/B) or returns 409 for existing registered user (Case C)
Mutation

Key Types

InviteInfo
email, customerName?, contractor.businessName, contractor.avatarUrl?, expiresAt
Schema
PageState
Union type: loading | error | expired | ready | claiming | success | existing_account
Schema
ClaimResult
success, error?, isNewAccount? — determines success screen variant
Schema

Integrations

SecureStore
Stores pending invite token for Case C redirect (1-hour expiry). Avoids token leakage in URL.
Integration
Linking.openURL
Opens 3bids.io/download (universal download page with platform detection)
Integration
Clerk Auth Redirect
Case C: redirects to /(auth)/sign-in?redirect=/poster/join/link
Integration

Magic Link State Machine

loading
ready
claiming
success
loading
expired
loading
error
claiming
existing_account
sign-in redirect

Key Design Decisions

3-Case Architecture

Case A: new user creates shadow account. Case B: existing shadow claims invite. Case C: registered user signs in to link. All handled by one screen.

Token Security

Tokens are SHA-256 hashed in storage. For Case C, token is moved to SecureStore with 1-hour expiry to prevent URL leakage during auth redirect.

Passwordless Onboarding

Zero-friction entry via magic link. No password creation, no email verification step. Contractor context pre-fills invite details.

Graceful Degradation

Network errors, missing tokens, storage failures, and mid-flow expiration all handled with distinct error states and recovery CTAs.