# Closed-Beta API Summary

This is the human-readable map for the current Activatist closed-beta API. The machine-readable contract is [openapi.yaml](/Users/massy/develop/code_buysell/docs/api/openapi.yaml).

## Public Buyer And Client APIs

These endpoints do not require seller/admin authentication.

| Endpoint | Purpose | Notes |
| --- | --- | --- |
| `GET /v1/public/products/{slug}` | Read safe public product metadata | Only approved/published products should be purchasable. |
| `POST /v1/public/products/{slug}/checkout` | Create a Stripe test-mode Checkout Session | Requires approved product, approved seller, and Stripe charges enabled. |
| `GET /purchase/complete` | Accountless buyer completion page shell | Completion tokens must be passed in URL fragment, not query string. |
| `POST /v1/purchases/complete` | Retrieve purchased generated license | Returns the raw license key only after valid completion-token authorization. |
| `POST /v1/purchases/files/{file_id}/download-intent` | Create short-lived private buyer download URL | Requires valid completion token and approved, buyer-visible, hash-verified, trusted-clean file. |
| `POST /v1/licenses/validate` | Validate a generated license key | Does not create or modify activations. |
| `POST /v1/licenses/activate` | Activate a generated license for a device | Hashes device fingerprint and enforces activation limits. |
| `POST /v1/licenses/deactivate` | Deactivate a device activation | Idempotent for unknown or already inactive activation. |

## Seller APIs

These require authenticated seller identity. Staging/prod should use verified Firebase bearer tokens and must not rely on local header-only auth.

| Endpoint | Purpose | Notes |
| --- | --- | --- |
| `POST /v1/sellers` | Create seller application | Seller still needs platform review. |
| `GET /v1/sellers/me` | Get current seller profile | Returns review and Stripe onboarding state. |
| `POST /v1/sellers/stripe/account-link` | Create Stripe Connect hosted onboarding link | Test mode for closed beta. |
| `POST /v1/sellers/stripe/refresh` | Refresh Stripe onboarding state | Retrieves current account state server-side. |
| `POST /v1/products` | Create product draft | First-party software-license-only boundary applies. |
| `GET /v1/products/{product_id}` | Get owned product | Seller-owned only. |
| `PATCH /v1/products/{product_id}` | Update owned product | Product review remains separate. |
| `POST /v1/products/{product_id}/submit-review` | Submit draft for admin review | Seller cannot self-approve. |
| `POST /v1/products/{product_id}/code-batches` | Optional CSV license import | Only for `imported_csv` products. |
| `POST /v1/products/{product_id}/files/upload-intent` | Create private file upload intent | Returns sensitive short-lived upload URL and required PUT headers. |
| `POST /v1/products/{product_id}/files/{file_id}/finalize` | Finalize private file upload | Moves file to `pending_review/private`; does not approve or expose it. |

## Admin APIs

These require verified allowlisted admin identity.

| Endpoint | Purpose | Notes |
| --- | --- | --- |
| `GET /v1/admin/sellers` | List seller applications | Admin review queue. |
| `PATCH /v1/admin/sellers/{seller_id}/review` | Review seller | Approve, approve_limited, needs_more_info, reject, or suspend. |
| `PATCH /v1/admin/products/{product_id}/review` | Review product | Product approval is separate from seller approval. |
| `GET /v1/admin/product-files` | List file review metadata | Omits storage bucket/key, presigned URLs, and credentials. |
| `PATCH /v1/admin/products/{product_id}/files/{file_id}/review` | Manual clean, approve, reject, or disable file | Manual clean does not approve; approve requires hash verified and trusted clean. |
| `POST /v1/admin/licenses/{license_id}/revoke` | Manual license revoke | Audited; validate/activate reject revoked licenses. |
| `POST /v1/admin/orders/{order_id}/completion-token` | Staging/local completion-token inspection | Disabled in production and not a buyer delivery path. |

## Internal/Ops APIs

| Endpoint | Purpose | Notes |
| --- | --- | --- |
| `POST /v1/stripe/webhook` | Stripe platform webhook | Handles Checkout/refund/dispute/payment-failure projections. |
| `POST /v1/stripe/connect/webhook` | Optional Connect/Accounts v2 webhook | Uses separate Connect webhook secret. |
| `GET /healthz` | Liveness | Lightweight process check. |
| `GET /readyz` | Readiness | Primary staging health check. |

Worker jobs such as outbox, file hash, file scan, and file upload cleanup are not HTTP integration APIs. Their operational docs live in the deployment and QA runbooks.

## Sensitive Data Rules

- Do not log or store raw license keys except through the authorized purchase completion response.
- Do not place completion tokens in query strings.
- Do not record buyer email plaintext in shared docs or logs.
- Do not record full presigned upload/download URLs outside the immediate client response.
- Do not expose R2 bucket/object keys, provider credentials, Firebase tokens, bearer tokens, Stripe secrets, Resend keys, or Cloudflare tokens.
- Do not treat `scan_engine=fake` as closed-beta clearance for seller files.

## Current Launch Boundary

Invite-only closed beta is GO WITH CONSTRAINT. Public launch and live Stripe mode remain NO-GO until the separate readiness items in [docs/planning/16_CLOSED_BETA_GO_NO_GO.md](/Users/massy/develop/code_buysell/docs/planning/16_CLOSED_BETA_GO_NO_GO.md) are cleared.