Dashboard/Scout/wiki/decisions/2026-07-03-self-service-beta-and-stripe-credit-packages.md
Scout

wiki/decisions/2026-07-03-self-service-beta-and-stripe-credit-packages.md

ADR: Self-Service Beta Registration And Stripe Credit Packages

Date: 2026-07-03 Status: Accepted

Context

Scout is moving from a private operator-provisioned beta toward production readiness for hosted SaaS usage. The product needs self-service access, measurement, metering, monitoring, and a payment path that can be verified before public launch. A shared invite password was rejected because it is a weak security boundary and adds friction without meaningful account identity.

The user goal requires:

  • people can register with name and email to get a beta tester API key;
  • Scout stores the account in its hosted account database;
  • Scout generates the API key and emails it;
  • the email is signed by Arijit;
  • credits are metered and visible;
  • paid usage uses Stripe;
  • beta can also verify payment-method setup at $0.

Decision

Scout will use two related self-service hosted access paths:

  1. Beta API key registration: /beta posts name and email to /v1/hosted/beta-key. The server provisions a hosted beta account, generates an API key, stores only key metadata/hash, and emails the raw key once.
  2. Stripe checkout for credits: /pricing posts to /v1/billing/stripe/checkout-session. The same checkout form exposes beta_trial as a $0 setup-mode Stripe checkout and paid credit packs such as $10 / 1,000 standard credits.

The beta path intentionally does not use a shared invite password. The API key is the hosted API credential, and /account lets users inspect balance, usage, and purchases by pasting that key without creating a login.

Rationale

  • Name plus email creates a real account record and makes usage attributable.
  • A shared password cannot identify users, meter individual behavior, or support revocation and credits cleanly.
  • Email delivery keeps raw API keys out of browser responses and preserves the one-time secret handoff model.
  • Failing closed when SMTP is missing is safer than returning a raw key in the browser; public self-service must not advertise or expose raw_api_key in HTTP responses or OpenAPI schemas.
  • $0 Stripe setup-mode checkout keeps the future payment pipeline testable without charging beta users.
  • Paid credit packages remain separate from the low-friction beta key path so beta onboarding can proceed while Stripe live/test-mode configuration is verified.

Alternatives Considered

Option Why rejected
Shared beta invite password Adds friction without real identity, user-level metering, or revocation.
Manual-only admin key provisioning Does not satisfy self-service beta onboarding.
Stripe-only beta onboarding Useful for payment verification, but it blocks beta access whenever Stripe or webhook config is not ready.
Login/password account portal now Deferred because API-key hosted usage and /account lookup are enough for the current beta control plane.

Consequences

  • Website /beta must stay aligned with /v1/hosted/beta-key.
  • /v1/hosted/beta-key must require configured key delivery and fail before account creation when delivery is missing.
  • Website /pricing must stay aligned with /v1/billing/packages and /v1/billing/stripe/checkout-session.
  • SMTP delivery must be configured and smoke-tested in production before the beta registration path can be considered live-ready.
  • Stripe checkout/webhook/key-delivery must be smoke-tested in test mode and production mode before paid self-service can be considered complete.
  • Pricing and credit packages remain subject to founder approval and unit economics review.

Current Credit Model

Action Credit cost
Hosted scrape 1 standard credit
Returned crawl page 1 standard credit
Product or intelligence record 1 standard credit
Screenshot 3 standard credits
Browser render 5 browser credits
Browser minute 10 browser credits

Current Package Model

Package Price Credits Notes
beta_trial $0 100 standard credits 30-day beta, setup-mode Stripe compatible, no browser credits
standard_1000 $10 1,000 standard credits Candidate pay-as-you-go package
standard_3000 $25 3,000 standard credits Volume candidate
standard_15000 $100 15,000 standard credits Heavier beta candidate

Verification

  • Website tests verify /beta uses name/email beta registration without a password and without the old hosted-keygen UI.
  • Website tests verify /pricing exposes beta_trial and paid credit package checkout options.
  • Hosted API tests verify /v1/hosted/beta-key is disabled unless configured, requires email delivery, rolls back on failed delivery, rejects duplicate emails, never returns the raw API key in the HTTP response, and does not advertise raw_api_key in the public response schema.
  • Stripe tests verify setup-mode checkout, paid checkout, webhook signature, provisioning, and idempotency behavior.
  • Hosted readiness tests verify scripts/hosted_readiness_check.py reports beta signup readiness only when signup and SMTP delivery are configured, and reports paid checkout readiness only when Stripe Checkout, Stripe webhook, and key delivery are configured. The checker ignores removed response-key fallback signals.

Current Production Readiness

As of 2026-07-03, production https://scout.chowmes.com reports:

  • Health: ready.
  • Billing package metadata: ready.
  • Beta registration: enabled, but key delivery is not complete until SMTP is configured.
  • Paid checkout: blocked.

Open production blockers:

  • SMTP key delivery is not configured.
  • Stripe Checkout is not configured.
  • Stripe webhook secret is not configured.
  • Paid checkout/key delivery is not ready.

Correction: older notes that promoted card-backed Stripe setup as the public beta entry point are superseded by 2026-07-03-email-first-beta-registration-supersedes-stripe-first.md. The currently deployed /beta page uses /v1/hosted/beta-key; Stripe remains the paid checkout and future card-backed verification path.