Dashboard/Scout/wiki/decisions/2026-07-03-direct-email-beta-key-registration.md
Scout

wiki/decisions/2026-07-03-direct-email-beta-key-registration.md

ADR: Direct Email Beta Key Registration

Date: 2026-07-03 Status: Accepted

Context

Scout needs a self-service beta path that is simple enough for testers and safe enough for hosted operations. A shared invite password was rejected. A browser raw-key fallback was also rejected because public signup must not show API keys in the page or OpenAPI schema. The previous website copy made the beta path look Stripe-checkout-first, which confused the direct beta tester API key requirement.

Decision

Use /beta as the public beta tester registration page. The form collects name and email, posts to POST /v1/hosted/beta-key, records the tester account in Scout's hosted account database, generates one hosted API key, and emails that key through the configured key-delivery service.

Stripe remains a separate path for paid credit packages and future card-backed beta validation. Direct beta key registration does not require Stripe.

Rationale

  • It matches the product intent: "register to get your Beta Tester API Key."
  • It removes password/invite-code friction.
  • It keeps raw API keys out of browser responses and public schemas.
  • It lets Scout fail closed when SMTP is missing, before creating an account.
  • It preserves the Stripe investment for paid/card-backed checkout without forcing that complexity onto the first beta key path.

Alternatives Considered

Option Why rejected
Shared beta invite password Adds friction, leaks easily, and does not identify who registered.
Raw key displayed in browser Unsafe for public signup and easy to leak in screenshots/logs.
Stripe setup-mode for all beta testers Useful later, but blocks basic beta key registration on Stripe configuration and webhook readiness.

Consequences

  • /v1/billing/stripe/status now reports ready_for_beta_key_delivery for the direct email-key path.
  • scripts/hosted_readiness_check.py uses ready_for_beta_key_delivery for beta signup readiness and keeps ready_for_paid_key_delivery for paid/card checkout readiness.
  • /beta uses website/assets/hosted-keygen.js and posts to /v1/hosted/beta-key.
  • Production still requires SMTP configuration before direct beta signup is live-ready.