{ "openapi": "3.1.0", "info": { "title": "Stevens Keys API (TEST MODE)", "version": "0.1.0-preview", "description": "License keys, validation and metering for MCP servers. TEST MODE: keys are sk_mcp_test_*, no real charges; checkout is Stripe test mode only; ledger shows simulated and Stripe-test sales; payouts (Stripe Connect) are not live. Accounts are verified for test mode by Cloudflare Turnstile at signup.", "contact": { "name": "Canada Site Ops" } }, "servers": [ { "url": "https://stevens-keys.pages.dev" } ], "components": { "securitySchemes": { "licenseKey": { "type": "http", "scheme": "bearer", "description": "License key sk_mcp_test_..." }, "creatorSecret": { "type": "http", "scheme": "bearer", "description": "Creator API secret sk_creator_test_..." }, "session": { "type": "apiKey", "in": "cookie", "name": "sk_session" } } }, "paths": { "/healthz": { "get": { "summary": "Health check", "operationId": "get_healthz", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/public-stats": { "get": { "summary": "Public aggregate adoption stats, last 60 days (no auth, CORS *, cached ~60s). Aggregates only: no emails, keys or ids. creators {outside, internal} (internal = demo sandbox, ops/Surface seed, test accounts); signups_by_day [{date, outside}]; api_calls_by_day [{date, agent, human, denied}] (agent/human = metered units, denied = denied calls); products and keys_issued exclude the demo sandbox; revenue_cad {test, live} = Stripe sales net of refunds; pageviews_by_day is [] (no server-side source); days_since_launch from 2026-10-11.", "operationId": "get_v1_public_stats", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/config": { "get": { "summary": "Public config: rev-share (planned 85/15), free tier, test_mode", "operationId": "get_v1_config", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/validate": { "post": { "summary": "Validate and meter a license key. 200 allow, 403 deny (status: invalid, revoked, suspended, expired, over_quota, wrong_product, product_archived, activation_limit, instance_required), 401 missing key. Optional instance_id (1-128 chars A-Za-z0-9._:-) identifies a device/installation; required when the product sets max_activations, and new instances beyond the cap get activation_limit. CORS open.", "operationId": "post_v1_validate", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "licenseKey": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string" }, "units": { "type": "integer" }, "meter": { "type": "boolean" }, "instance_id": { "type": "string" } } } } } } } }, "/v1/auth/signup": { "post": { "summary": "Create a creator account. Requires a passing Cloudflare Turnstile token; passing marks the account test_verified (test keys + test checkout). No email is sent.", "operationId": "post_v1_auth_signup", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" }, "display_name": { "type": "string" }, "turnstile_token": { "type": "string" } } } } } } } }, "/v1/auth/login": { "post": { "summary": "Log in; sets session cookie", "operationId": "post_v1_auth_login", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "password": { "type": "string" } } } } } } } }, "/v1/auth/logout": { "post": { "summary": "Log out", "operationId": "post_v1_auth_logout", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/auth/verify-email": { "post": { "summary": "Verify email with a token", "operationId": "post_v1_auth_verify_email", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } } } } } } } }, "/v1/auth/resend-verification": { "post": { "summary": "Resend verification (email sending is currently disabled; returns email_delivery: unavailable)", "operationId": "post_v1_auth_resend_verification", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/auth/password-reset/request": { "post": { "summary": "Request a password reset (always the same 200 body; while email is unavailable it says so and gives a contact address)", "operationId": "post_v1_auth_password_reset_request", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" } } } } } } } }, "/v1/auth/password-reset/confirm": { "post": { "summary": "Confirm password reset", "operationId": "post_v1_auth_password_reset_confirm", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "password": { "type": "string" } } } } } } } }, "/v1/verification-request": { "get": { "summary": "Get your manual early-access review request (required before anything live)", "operationId": "get_v1_verification_request", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] }, "post": { "summary": "Request manual early-access review", "operationId": "post_v1_verification_request", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/demo/keys": { "post": { "summary": "Issue a sandbox demo key (50 calls, 24h expiry)", "operationId": "post_v1_demo_keys", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/demo/revoke": { "post": { "summary": "Revoke a sandbox demo key", "operationId": "post_v1_demo_revoke", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" } } } } } } } }, "/v1/public/products/{id}": { "get": { "summary": "Public product info for the /buy page (name, description, price_cents, currency CAD, test_mode). 404 unless the product is active, priced (>= 50 cents) and owned by a verified creator. No auth.", "operationId": "get_v1_public_products_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/checkout": { "post": { "summary": "Create a Stripe Checkout Session (TEST MODE, mode=payment, CAD, adaptive pricing off) for a priced product of a verified creator. Live in Stripe test mode (test cards only, no real money). Live keys and livemode sessions are refused.", "operationId": "post_v1_checkout", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string" } } } } } } } }, "/v1/checkout/reveal": { "post": { "summary": "Single reveal of the license key bought in a Checkout Session (202 pending, 200 key once, 410 already revealed)", "operationId": "post_v1_checkout_reveal", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string" } } } } } } } }, "/v1/stripe/webhook": { "post": { "summary": "Stripe webhook (Stripe-Signature HMAC-SHA256, 300s tolerance, idempotent on event id). Issues a key on checkout.session.completed / async_payment_succeeded when paid. Livemode events ignored.", "operationId": "post_v1_stripe_webhook", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [] } }, "/v1/auth/turnstile-verify": { "post": { "summary": "Pass Turnstile to become test_verified (for accounts created before the check)", "operationId": "post_v1_auth_turnstile_verify", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "turnstile_token": { "type": "string" } } } } } } } }, "/v1/account": { "delete": { "summary": "Delete your account: re-confirm password; revokes all keys and deletes all creator data", "operationId": "delete_v1_account", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string" } } } } } } } }, "/v1/me": { "get": { "summary": "Current creator", "operationId": "get_v1_me", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/api-secrets": { "get": { "summary": "List creator API secrets", "operationId": "get_v1_api_secrets", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] }, "post": { "summary": "Create a creator API secret (shown once; requires verified account)", "operationId": "post_v1_api_secrets", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/api-secrets/{id}/revoke": { "post": { "summary": "Revoke a creator API secret", "operationId": "post_v1_api_secrets_id_revoke", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/products": { "get": { "summary": "List products", "operationId": "get_v1_products", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] }, "post": { "summary": "Create a product", "operationId": "post_v1_products", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "plan": { "type": "string" }, "monthly_quota": { "type": "integer" }, "max_activations": { "type": "integer" }, "price_cents": { "type": "integer" }, "cache_ttl": { "type": "integer" }, "fail_mode": { "type": "string" }, "upstream_url": { "type": "string" } } } } } } } }, "/v1/products/{id}": { "get": { "summary": "Get a product", "operationId": "get_v1_products_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "summary": "Update a product", "operationId": "patch_v1_products_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "plan": { "type": "string" }, "monthly_quota": { "type": "integer" }, "max_activations": { "type": "integer" }, "price_cents": { "type": "integer" }, "cache_ttl": { "type": "integer" }, "fail_mode": { "type": "string" }, "upstream_url": { "type": "string" } } } } } } }, "delete": { "summary": "Archive a product (its keys then deny with product_archived)", "operationId": "delete_v1_products_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/keys": { "get": { "summary": "List license keys (optional ?product_id=)", "operationId": "get_v1_keys", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] }, "post": { "summary": "Issue a license key; plaintext returned once (requires verified account)", "operationId": "post_v1_keys", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string" }, "label": { "type": "string" }, "monthly_quota": { "type": "integer" }, "expires_at": { "type": "integer" } } } } } } } }, "/v1/keys/{id}": { "get": { "summary": "Get a key with live counters", "operationId": "get_v1_keys_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/keys/{id}/activations": { "get": { "summary": "List instances (devices) that activated this key, with the product's max_activations", "operationId": "get_v1_keys_id_activations", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "delete": { "summary": "Reset all activations for this key (frees every slot)", "operationId": "delete_v1_keys_id_activations", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/keys/{id}/activations/{instance_id}": { "delete": { "summary": "Deactivate one instance, freeing its slot", "operationId": "delete_v1_keys_id_activations_instance_id", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "instance_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } } ] } }, "/v1/keys/{id}/revoke": { "post": { "summary": "Revoke a key (terminal; next validation denies)", "operationId": "post_v1_keys_id_revoke", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/keys/{id}/suspend": { "post": { "summary": "Suspend a key", "operationId": "post_v1_keys_id_suspend", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/keys/{id}/resume": { "post": { "summary": "Resume a suspended key", "operationId": "post_v1_keys_id_resume", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/usage": { "get": { "summary": "Usage rollups (?product_id=&days=30)", "operationId": "get_v1_usage", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/revenue": { "get": { "summary": "Revenue (test mode, CAD, 85/15): simulated demo sales plus Stripe test sales, net of refunds; no real money", "operationId": "get_v1_revenue", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/sales/{id}/refund": { "post": { "summary": "Refund one of your own Stripe TEST sales (creator session). Body {amount_cents?} (default: remaining amount; partial allowed). Creates a Stripe test refund and returns 202; the charge.refunded webhook then writes a negative refund ledger row (idempotent per refund id) and, when fully refunded, revokes the key immediately. 409 not_refundable for simulated sales, 409 already_refunded.", "operationId": "post_v1_sales_id_refund", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount_cents": { "type": "integer" } } } } } } } }, "/v1/ledger/simulate-sale": { "post": { "summary": "Record a simulated demo sale (test mode only; no real money)", "operationId": "post_v1_ledger_simulate_sale", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string" }, "gross_cents": { "type": "integer" }, "key_id": { "type": "string" } } } } } } } } } }