ADR: Direct Beta Email Delivery With Optional Card-Backed Setup

Date: 2026-07-03 Status: accepted

Decision

Scout beta access has two self-service paths:

1. Primary low-friction path: direct name/email registration through POST /v1/hosted/beta-key.
2. Secondary payment-pipeline verification path: $0 Stripe setup-mode checkout for beta_trial when Stripe Checkout, webhook signing, and SMTP key delivery are configured.

When hosted beta signup and SMTP delivery are configured, Scout provisions a finite-credit hosted_beta_pass tenant, generates a one-time raw API key, emails that key to the registered address, and records a delivered signup event. The browser/API response never returns raw_api_key.

If SMTP delivery is not configured, Scout records a pending signup request and does not create an account, key, or credits.

Stripe remains the paid hosted-credit checkout path and the optional $0 card-backed beta setup path. It is not a shared-password or manual invite gate.

Clarifies

This clarifies the earlier card-backed beta setup direction captured in:

• 2026-07-03-card-backed-beta-with-email-queue-fallback.md
• 2026-07-03-beta-specific-stripe-return-urls.md
• parts of 2026-07-03-email-first-beta-registration-supersedes-stripe-first.md

Those files remain as history. This ADR is the current operating decision: email registration is primary, card-backed setup is optional/secondary, and both paths are self-service.

Rationale

The product goal is lower-friction beta testing. Requiring Stripe for a free beta key creates unnecessary friction before the value of the hosted service is proven. Direct email delivery gives testers a normal SaaS-style API-key onboarding path while still preserving measurement, metering, and a finite credit boundary. The optional $0 setup path keeps the future paid billing pipeline verifiable without forcing every beta tester through Stripe first.

Consequences

• /beta is the public beta registration page.
• /v1/hosted/beta-key is the self-service beta key endpoint.
• ready_for_beta_key_delivery is the readiness flag for beta signup.
• ready_for_beta_checkout is the readiness flag for optional $0 card-backed beta setup.
• Paid packages still use /v1/billing/stripe/checkout-session.
• SMTP delivery is the primary production blocker for direct beta self-service.
• Stripe Checkout, webhook signing, and SMTP delivery are blockers for optional $0 card-backed beta setup.

Verification

Validated in code with focused tests:

• tests/unit/api/test_hosted_scrape.py
• tests/unit/api/test_billing_stripe_checkout.py
• tests/unit/scripts/test_hosted_readiness_check.py
• tests/unit/website/test_launch_website.py
• tests/unit/test_hosted_pricing_docs.py

The combined focused run reported 88 passed, 2 warnings.