Dashboard/Scout/wiki/decisions/2026-07-03-email-first-beta-registration-supersedes-stripe-first.md
Scout

wiki/decisions/2026-07-03-email-first-beta-registration-supersedes-stripe-first.md

ADR: Email-First Beta Registration Supersedes Stripe-First Beta Onboarding

Date: 2026-07-03 Status: Accepted

Context

Scout's hosted beta onboarding records contained conflicting decisions. Earlier work explored a card-backed $0 Stripe setup flow as the public beta path, but the currently deployed product surface at https://scout.chowmes.com/beta and the live hosted status endpoint now use direct name/email beta registration.

The status endpoint contract now reports:

  • public_self_service_path: email_beta_registration_with_checkout_hook
  • public_beta_key_endpoint: /v1/hosted/beta-key
  • beta_signup_enabled: true
  • checkout/webhook/key-delivery readiness as separate booleans

Decision

The public beta path is email-first registration through POST /v1/hosted/beta-key. Stripe remains the paid checkout path and may be used through the existing $0 beta setup hook once checkout is fully configured, but the public copy and primary button should not advertise checkout-first onboarding while production is blocked by external Stripe/SMTP configuration.

Rationale

  • Email-first registration is lower friction for private beta testers.
  • It avoids shared beta passwords while still capturing name and email.
  • It lets Scout record pending signups even before SMTP delivery is configured.
  • It keeps raw API keys out of browser responses and OpenAPI schemas.
  • Stripe setup remains valuable for paid checkout and future payment-method verification, but it should not block the first beta signup surface.

Alternatives Considered

Option Why rejected
Shared invite password before key creation Weak attribution, easy sharing, poor SaaS onboarding pattern.
Stripe-first $0 beta setup as the only public path Useful later, but currently blocks beta access on Stripe secret, webhook, and SMTP setup.
Manual admin key generation only Works for emergency internal consumers, but does not satisfy self-service beta onboarding.
Returning raw API keys in the browser Rejected for security; the one-time raw key is delivered by email when SMTP is configured.

Consequences

  • /beta uses hostedKeyForm and posts to /v1/hosted/beta-key.
  • /v1/billing/stripe/status exposes the beta path as email_beta_registration_with_checkout_hook.
  • Missing SMTP means signups are queued as pending_delivery; no account, key, or credits are created until delivery can happen.
  • Operators must configure SMTP and then process pending signups before calling beta self-service fully operational.
  • Paid credit packages remain blocked until Stripe secret, price IDs, success/cancel URLs, webhook secret, and SMTP delivery are configured and smoke-tested.
  • Older vault notes saying "public beta signup is Stripe setup first" or "card-backed beta with email queue fallback is primary" are superseded by this ADR and should be treated as historical context only.

Verification

  • Repo: /Users/arijitchowdhury/Dropbox/AI-Development/Scout
  • Branch: codex/scout-saas-prod-ready
  • Latest local correction: beta page copy and /v1/billing/stripe/status contract now use email-first registration with a checkout hook.
  • Public beta page contains hostedKeyForm, /v1/hosted/beta-key, and Register for Beta API Key.
  • Public beta page keeps /v1/billing/stripe/checkout-session only as a readiness-gated hook, not as the primary public CTA.
  • Focused verification for the latest correction reported:
  • 91 passed, 2 warnings
  • Pyright: 0 errors
  • Ruff: all checks passed

Remaining Work

  1. Configure hosted SMTP delivery.
  2. Smoke-test hosted key email delivery.
  3. Drain pending_delivery beta signups.
  4. Configure Stripe secret, success/cancel URLs, paid package price IDs, and webhook secret.
  5. Run Stripe checkout, webhook, credit top-up, and emailed-key delivery smoke.