Feature: Auth
Tied to journey: Auth soft-gate.
Locked contract
- Provider: WorkOS AuthKit.
- Methods: Apple + Google + Magic Auth (email OTP).
- Passwords: Not supported in MVP; there is no password creation, login, reset, or recovery flow.
- Native handoff: System browser sheet with PKCE; Android / iOS package
com.pocketlabs.clubhouseleague. - Schemes (staging vs prod):
- Staging (default for staging builds): redirect
clubhouseleague-staging://auth/callback; logout / returnToclubhouseleague-staging://signed-out. - Production: redirect
clubhouseleague://auth/callback; logout / returnToclubhouseleague://signed-out.
- Staging (default for staging builds): redirect
- Staging Client ID:
client_01M2VWKF87Q557H9D37BFKC52H(public). A production Client ID exists, but production WorkOS mutations remain locked until billing — do not point production builds at staging. - Profile:
workos_user_id,email, anddisplay_nameare required before creating a league or joining;avataris optional. - Server verification: APIs verify WorkOS JWTs using WorkOS JWKS and return
401 Unauthorizedfor missing, invalid, expired, or unverifiable credentials.
Product acceptance criteria
- Soft-gate: unauthenticated users can open onboarding and browse discoverable leagues without forced login.
- Create league, request to join, and redeem invite code require a valid authenticated session.
- The app preserves the pending action through auth and resumes it only after required profile completion.
- Apple, Google, and Magic Auth (email OTP) are available; no password path exists.
- Cancelled or failed auth cannot create a league or write membership.
- A stale-session
401clears local session state and returns the user to the auth gate; browse/onboarding remain available.
Architecture
Design/structure for the soft-gate. Product locks stay above; eng how-to and tickets stay in Implementation notes.
- Client surfaces — Auth is not a top-nav product surface; it is a gate invoked from onboarding, league browse, create-league, request-to-join, and invite-code redeem. iOS and Android twins share the same soft-gate behavior: system browser sheet + PKCE, then resume of the pending action after profile completion.
- Domain model — Session (access/refresh tokens from AuthKit), verified identity keyed by
workos_user_id, and profile fieldsemail(required),display_name(required before gated writes),avatar(optional). Pending-action resume state holds the intended write (create / request-join / redeem) plus league or invite-code context; that state is not authorization. - Data & APIs — Reed owns the auth contract: APIs verify WorkOS JWTs against WorkOS JWKS and reject missing, invalid, expired, or unverifiable credentials with
401. Server uses the verified WorkOS subject asworkos_user_idand never trusts a client-provided user ID. Profile upsert precedes membership writes. - Cross-feature dependencies — Auth gates all membership and league-creation writes (see Leagues). Browse of discoverable leagues remains available signed-out. Soft-gate also applies before draft, roster, and waiver mutations once those surfaces exist (MVP scope). Roles matrix: Roles & permissions.
- Platform notes — Package
com.pocketlabs.clubhouseleague. Staging AuthKit Client IDclient_01M2VWKF87Q557H9D37BFKC52Hwith schemesclubhouseleague-staging://auth/callbackandclubhouseleague-staging://signed-out(prod schemesclubhouseleague://…). Staging redirect and logout URIs are allowlisted on WorkOS; staging builds must use the staging Client ID + staging schemes. OD-9 progress: staging schemes locked; remaining TBD are Universal Links hosts, assetlinks / associated domains, and any extra WorkOS HTTPS allowlist hosts — see Ops → Auth deep-link hosts. Client twins must not embed credential forms.
Implementation notes
- AuthKit is an implementation dependency, not a product nav item — see Architecture.
- Prefer the system browser sheet and PKCE; do not ship an embedded password or credential form.
- On
401, clear local session and return to the soft-gate without blocking browse/onboarding. - Ownership: Product Morgan; Eng Remy disburses to Kit/Dex; Auth contract Reed; Design Mira for this runbook only (app UI on hold).
- Delivery tickets: iOS #3 and Android #2.
- Delivery pointers: Auth delivery.