Skip to main content

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 / returnTo clubhouseleague-staging://signed-out.
    • Production: redirect clubhouseleague://auth/callback; logout / returnTo clubhouseleague://signed-out.
  • 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, and display_name are required before creating a league or joining; avatar is optional.
  • Server verification: APIs verify WorkOS JWTs using WorkOS JWKS and return 401 Unauthorized for 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 401 clears 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 fields email (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 as workos_user_id and 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 ID client_01M2VWKF87Q557H9D37BFKC52H with schemes clubhouseleague-staging://auth/callback and clubhouseleague-staging://signed-out (prod schemes clubhouseleague://…). 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.