{ "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, revenue is simulated, payouts (Stripe Connect) are planned and not live. Accounts are verified manually during early access.", "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/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, 401 missing key. 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" } } } } } } } }, "/v1/auth/signup": { "post": { "summary": "Create a creator account (unverified; verification is manual during early access)", "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" } } } } } } } }, "/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 returns the same 200 body)", "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 early-access manual verification request", "operationId": "get_v1_verification_request", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] }, "post": { "summary": "Request early-access manual verification", "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/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" }, "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" }, "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}/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": "Simulated revenue ledger (test mode, CAD, 85/15)", "operationId": "get_v1_revenue", "responses": { "200": { "description": "OK" }, "4XX": { "description": "Error: {\"error\": code}" } }, "security": [ { "creatorSecret": [] }, { "session": [] } ] } }, "/v1/ledger/simulate-sale": { "post": { "summary": "Record a simulated sale (test mode only; no money moves)", "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" } } } } } } } } } }