{ "openapi": "3.0.3", "info": { "title": "Run402 API", "version": "2.0.0", "description": "Full-stack infrastructure for AI agents. Postgres, REST API, auth, file storage, static site hosting, serverless functions. Tier payments and image generation use the shared payment engine: x402 (USDC on Base), MPP on Tempo (pathUSD), and the draft-pinned MPP Lightning charge profile (sats, Bitcoin mainnet) for authenticated tier purchases and image generation.", "contact": { "name": "Run402", "url": "https://run402.com" }, "guidance": "Run402 is a pay-per-use backend for AI agents: Postgres databases, static hosting, serverless functions, and image generation. The shared payment engine supports x402 (USDC on Base), MPP on Tempo (pathUSD), and the exact Run402 MPP Lightning charge profile on Bitcoin mainnet (sats).\n\n## Quick start\n1. Install the CLI: npm install -g run402@latest\n2. Create an allowance: run402 init\n3. Subscribe to prototype tier (FREE, testnet USDC): run402 tier set prototype\n4. Provision a project: run402 projects provision --name \"my-app\"\n5. Deploy: run402 deploy --manifest app.json\n\n## Payment model\n- Tier subscriptions (prototype $0.10 testnet, hobby $5, team $20) unlock all platform features.\n- Image generation is $0.03 per call (x402, MPP on Tempo, or MPP Lightning micropayment).\n- Auth-only endpoints (projects, deploys, messages) require SIWX wallet identity but no payment.\n\n## Auth\n- x402 endpoints: include a payment header (handled automatically by the CLI or x402 client libraries).\n- Explicit MPP Lightning tier requests require the exact Run402 profile, ordered Accept-Payment preferences, one principal credential, a stable Idempotency-Key, and buyer-side USD/native/fee limits.\n- SIWX endpoints: sign a CAIP-122 message with your wallet.\n- REST API: use the project's anon_key or service_key as the apikey header.\n\n## Client metadata\n- Recent Node SDK/CLI clients may send Run402-Client: surface=\"cli\", version=\"3.7.14\", sdk=\"3.7.14\". It is advisory, bounded, never used for auth/billing/trust, and not browser-CORS-enabled yet.\n\n## Docs\n- Full CLI docs: https://run402.com/llms-cli.txt\n- API docs: https://run402.com/llms.txt" }, "servers": [ { "url": "https://api.run402.com", "description": "Production" } ], "tags": [ { "name": "Operator console", "description": "Read-only organization overview for the human operator (Phase 0, add-operator-console). API-first: the reference web console is just a consumer of these endpoints." }, { "name": "Tiers", "description": "Wallet-level tier subscription — subscribe, renew, upgrade, and check status" }, { "name": "Projects", "description": "Provision and manage database projects (wallet auth, free within tier)" }, { "name": "Project Archives", "description": "Portable archive export for the supported Run402 Core runtime slice of a Cloud project. This is the no-lock-in path, not a backup/SLA or allowance/spend-cap feature." }, { "name": "Auth", "description": "User signup, login, token refresh, and logout" }, { "name": "Admin", "description": "SQL migrations, RLS policies, usage, and schema introspection" }, { "name": "REST", "description": "PostgREST proxy — full CRUD on your tables" }, { "name": "Storage", "description": "Upload, download, delete, sign, and list files" }, { "name": "Faucet", "description": "Testnet USDC drip for development" }, { "name": "Deployments", "description": "Static site deployment (wallet auth, free within tier)" }, { "name": "Feedback", "description": "Feedback / contact endpoint (wallet auth, free within tier)" }, { "name": "Subdomains", "description": "Custom subdomain management for deployments" }, { "name": "Functions", "description": "Serverless function deploy, invoke, logs, and secrets" }, { "name": "Health", "description": "Health check and x402 discovery" }, { "name": "Billing", "description": "Prepaid allowance accounts and checkout" }, { "name": "Bundle", "description": "One-call full-stack app deployment (wallet auth, free within tier)" }, { "name": "Publish", "description": "Publish and fork app versions" }, { "name": "Image", "description": "AI image generation (x402-gated, per-call)" }, { "name": "Agent", "description": "Agent contact registration (wallet auth, free within tier)" }, { "name": "Project domains", "description": "Project-scoped desired/observed/effective lifecycle for custom web and email domains" }, { "name": "Mailboxes", "description": "Project-scoped email at slug@project-host.mail.run402.com, with ProjectDomain custom addresses and managed fallback" }, { "name": "Content", "description": "v1.34 generic CAS content plan/commit (used internally by the SDK for byte uploads)." }, { "name": "Apply", "description": "Unified apply primitive — plan + commit + operations + resume." }, { "name": "Vouchers", "description": "Credit vouchers: single-use promo codes redeemable by an authenticated wallet for platform prepaid credit. Redeemed credit spends like any other prepaid balance (tiers, priced calls). Redemption works before or after `run402 init` and is never blocked by an organization grace state." } ], "paths": { "/agent/v1/operator/session/email": { "post": { "tags": [ "Operator console" ], "summary": "Send operator sign-in magic link", "description": "Public, rate-limited. Identical response whether or not the email controls an account (no account-existence oracle). A single-use link (raw token in the URL fragment) is emailed only when the email controls >=1 verified wallet.", "operationId": "operatorSessionEmail", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "return_path": { "type": "string", "pattern": "^/buzz/adoptions/buzzhao_[0-9a-f]{32}$", "description": "Optional ephemeral Buzz-adoption return path. The magic link carries it in the console fragment; the resulting session remains memory-only in that browser page." } } } } } }, "responses": { "200": { "description": "Generic acknowledgement (sent-if-eligible).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/email/verify": { "post": { "tags": [ "Operator console" ], "summary": "Exchange magic-link token for an operator session", "operationId": "operatorSessionEmailVerify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ operator_session_token, token_type, expires_in, absolute_expires_at, email, wallets[] }", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/passkey/options": { "post": { "tags": [ "Operator console" ], "summary": "WebAuthn authentication options for passkey-login", "operationId": "operatorSessionPasskeyOptions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "{ options } — PublicKeyCredentialRequestOptionsJSON.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/passkey/verify": { "post": { "tags": [ "Operator console" ], "summary": "Exchange a WebAuthn assertion for an operator session", "operationId": "operatorSessionPasskeyVerify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "response" ], "properties": { "email": { "type": "string", "format": "email" }, "response": { "type": "object" } } } } } }, "responses": { "200": { "description": "{ operator_session_token, token_type, expires_in, absolute_expires_at, email, wallets[] }", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/passkey/enroll/options": { "post": { "tags": [ "Operator console" ], "summary": "WebAuthn registration options to enroll an operator passkey", "description": "Operator-session-authed. Enroll a new passkey for the verified-email operator (binds to a verified wallet). Unlocks Tier-B inventory reads, which require a passkey session.", "operationId": "operatorPasskeyEnrollOptions", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "{ options } — PublicKeyCredentialCreationOptionsJSON.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/passkey/enroll/verify": { "post": { "tags": [ "Operator console" ], "summary": "Verify a WebAuthn registration + persist the operator passkey", "operationId": "operatorPasskeyEnrollVerify", "security": [ { "operatorSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object" }, "label": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ ok, credential_id }", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/refresh": { "post": { "tags": [ "Operator console" ], "summary": "Refresh (rotate) an operator session before expiry", "description": "Auth-plane write: rotates jti + re-issues while the session row is live and within the 12h absolute cap.", "operationId": "operatorSessionRefresh", "security": [ { "operatorSession": [] } ], "responses": { "200": { "description": "{ operator_session_token, token_type, expires_in }", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/device": { "post": { "tags": [ "Operator console" ], "summary": "Start a CLI device-authorization (RFC 8628)", "description": "Public, no oracle (email-less). Begins a browser-delegated device grant so the run402 CLI can obtain an operator session. Returns { device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }.", "operationId": "operatorSessionDeviceStart", "responses": { "200": { "description": "Device-authorization start payload.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/device/approve": { "post": { "tags": [ "Operator console" ], "summary": "Approve (or deny) a CLI device authorization", "description": "Operator-session-authed; the session must have authenticated recently (magic-link OR passkey). Binds the user_code to an approve/deny decision. Does NOT mint a session — the mint happens at the token poll.", "operationId": "operatorSessionDeviceApprove", "security": [ { "operatorSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_code" ], "properties": { "user_code": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "deny" ] } } } } } }, "responses": { "200": { "description": "{ ok, decision, client_name }", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/device/token": { "post": { "tags": [ "Operator console" ], "summary": "Poll for the operator session (RFC 8628 token endpoint)", "description": "Public; the device_code is the credential. On approval returns { operator_session_token, token_type, expires_in, absolute_expires_at, email, wallets[] } (single-use). Otherwise an RFC-8628 error body { error } at HTTP 400: authorization_pending | slow_down | access_denied | expired_token.", "operationId": "operatorSessionDeviceToken", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "device_code" ], "properties": { "device_code": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ operator_session_token, ... } on approval.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "RFC 8628 error body { error }.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/session/revoke": { "post": { "tags": [ "Operator console" ], "summary": "Revoke (sign out) the current operator session", "description": "Operator-session-authed. Revokes the current session by its jti via the existing revoke helper; idempotent; 204. Takes effect on the next request (the middleware checks revoked_at with no positive-validity cache).", "operationId": "operatorSessionRevoke", "security": [ { "operatorSession": [] } ], "responses": { "204": { "description": "Revoked (idempotent)." } } } }, "/agent/v1/operator/overview": { "get": { "tags": [ "Operator console" ], "summary": "Organization overview (Tier-A summary)", "description": "Multi-account, summary-first read: { scope, operator, rollup, organizations[], wallets[], advisories[] }. Counts only (functions/secrets/domains/mailboxes) — NOT inventory names. Accepts an operator session (verified-email union), a control-plane session (the console's write-capable sign-in reading its OWN footprint — verified-email + siwx-authenticator union; scope.kind \"principal\"), OR a wallet SIWX header (that wallet's slice). Service/admin keys are NOT accepted here.", "operationId": "operatorOverview", "security": [ { "operatorSession": [] }, { "controlPlaneSession": [] }, { "walletAuth": [] } ], "responses": { "200": { "description": "AccountOverview (Tier A).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/projects": { "get": { "tags": [ "Operator console" ], "summary": "Cross-account project inventory (--all)", "description": "Named, domain-aware project inventory across the operator's verified-email wallet union (or a single wallet's slice for a SIWX caller), in the same row shape as GET /projects/v1: { projects: [{ project_id, name, tier, site_url, custom_domains, status, org_id, created_by, created_at }], scope }. Soft-deleted (tombstone) projects are NEVER listed; archived projects are hidden by default and opt back in with `include=archived`. Names + public addressing only — no secret/key values. Service/admin keys are NOT accepted here.", "operationId": "operatorProjectInventory", "security": [ { "operatorSession": [] }, { "walletAuth": [] } ], "parameters": [ { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "archived" ] }, "description": "Opt archived projects back into the listing (`include=archived`). Soft-deleted (tombstone) projects are never returned regardless. Any other value is a 400." } ], "responses": { "200": { "description": "Named cross-account project inventory.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/projects/{project_id}/contents": { "get": { "tags": [ "Operator console" ], "summary": "Project inventory names (Tier-B drill-down)", "description": "Inventory NAMES (secret names, function names, domains, subdomains, mailbox slugs) — never values. Operator session requires fresh proof (passkey-login or recent re-auth); the project must be owned by a wallet in the caller's set.", "operationId": "operatorProjectContents", "security": [ { "operatorSession": [] }, { "walletAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ProjectContents (Tier B).", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/admin/v1/operator/overview": { "get": { "tags": [ "Operator console" ], "summary": "Operator overview for support (admin only, audited)", "description": "Support read. Mandatory exactly-one target query + a mandatory audit-log row. Same response schema as the public overview.", "operationId": "operatorOverviewAdmin", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "format": "email" } }, { "name": "wallet", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "org_id", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "AccountOverview.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth/v1/account/security": { "get": { "tags": [ "Auth" ], "summary": "Account security overview", "description": "Machine route (apikey + user Bearer). Returns the signed-in user's security surface: linked identities, registered passkeys, password-set state, and — with ?app_origin — current-RP passkey availability.", "operationId": "getAuthAccountSecurity", "security": [ { "apikey": [], "bearerAuth": [] } ], "parameters": [ { "name": "app_origin", "in": "query", "required": false, "schema": { "type": "string", "format": "uri" }, "description": "Exact app origin to evaluate for current-RP passkey state." } ], "responses": { "200": { "description": "Account security state.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/sessions": { "get": { "tags": [ "Auth" ], "summary": "List the Bearer actor's browser sessions", "description": "Machine route (apikey + user Bearer). Returns live, secret-free browser-session summaries for the user identified by the access token.", "operationId": "listAuthV1AccountSessions", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Live browser sessions for the Bearer actor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "type": "object", "required": [ "session_id", "created_at", "last_refreshed_at", "expires_at", "hard_expires_at", "amr", "passkey_id" ], "properties": { "session_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "last_refreshed_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "hard_expires_at": { "type": "string", "format": "date-time" }, "amr": { "type": "array", "items": { "type": "string" } }, "passkey_id": { "type": "string", "nullable": true } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/sessions/revoke": { "post": { "tags": [ "Auth" ], "summary": "Revoke one browser session as the Bearer actor", "description": "Machine route (apikey + user Bearer). Revokes one browser session by id, scoped to the user identified by the token; it cannot target another user's session.", "operationId": "revokeAuthV1AccountSession", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Revocation result; revoked is false when no matching live session exists.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "revoked" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "revoked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/sign-out-everywhere": { "post": { "tags": [ "Auth" ], "summary": "Revoke all browser sessions as the Bearer actor", "description": "Machine route (apikey + user Bearer). Revokes every live browser session for the token's user. Unlike the hosted-cookie route, a Bearer caller has no current browser session to preserve.", "operationId": "signOutEverywhereAuthV1Account", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Number of browser sessions revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "revoked_count" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "revoked_count": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/password": { "post": { "tags": [ "Auth" ], "summary": "Set or change the Bearer actor's password", "description": "Machine route (apikey + user Bearer). Requires the signed auth_time claim to be no more than 5 minutes old; otherwise returns R402_AUTH_FRESHNESS_REQUIRED. Refresh-token rotation preserves auth_time and does not satisfy freshness. A successful change revokes all of the user's browser sessions.", "operationId": "setAuthV1AccountPassword", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_password" ], "properties": { "new_password": { "type": "string", "minLength": 1, "description": "New password, limited to 72 UTF-8 bytes." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Password changed and browser sessions revoked.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "sessions_revoked" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "sessions_revoked": { "type": "integer", "minimum": 0 } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/passkeys": { "get": { "tags": [ "Auth" ], "summary": "List the Bearer actor's passkeys", "description": "Machine route (apikey + user Bearer). Lists active Run402 passkeys owned by the token's user. To register a passkey, use the WebAuthn registration routes under /auth/v1/passkeys/register/*.", "operationId": "listAuthV1AccountPasskeys", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Active passkeys for the Bearer actor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "passkeys" ], "properties": { "passkeys": { "type": "array", "items": { "type": "object", "required": [ "id", "rp_id", "created_at" ], "properties": { "id": { "type": "string" }, "rp_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/passkeys/remove": { "post": { "tags": [ "Auth" ], "summary": "Remove one of the Bearer actor's passkeys", "description": "Machine route (apikey + user Bearer). Requires auth_time within 5 minutes, soft-deletes one actor-owned passkey, and warns rather than refuses when no Run402 password or passkey remains.", "operationId": "removeAuthV1AccountPasskey", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "passkey_id" ], "properties": { "passkey_id": { "type": "string" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Passkey removal result.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "removed", "warning" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "removed": { "type": "boolean" }, "warning": { "type": "string", "nullable": true, "enum": [ "no_run402_password_or_passkey_remaining" ] } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/identities": { "get": { "tags": [ "Auth" ], "summary": "List the Bearer actor's linked OAuth identities", "description": "Machine route (apikey + user Bearer). Lists Run402-verified OAuth identities owned by the token's user. Pass an identity's provider_sub value as subject to the unlink route.", "operationId": "listAuthV1AccountIdentities", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Linked OAuth identities for the Bearer actor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "identities" ], "properties": { "identities": { "type": "array", "items": { "type": "object", "required": [ "provider", "provider_sub", "provider_email", "created_at" ], "properties": { "provider": { "type": "string" }, "provider_sub": { "type": "string" }, "provider_email": { "type": "string", "format": "email", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/account/identities/unlink": { "post": { "tags": [ "Auth" ], "summary": "Unlink one of the Bearer actor's OAuth identities", "description": "Machine route (apikey + user Bearer). Requires auth_time within 5 minutes. Removes the actor-owned OAuth identity selected by provider and provider subject, then revokes all browser sessions when a row was removed. The caller cannot supply a user id and a service-role token is rejected.", "operationId": "unlinkAuthV1AccountIdentity", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "subject" ], "properties": { "provider": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1, "description": "Provider subject id; use provider_sub from an account identity read." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Identity unlink result; unlinked is false when the actor owns no matching identity.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "unlinked" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "unlinked": { "type": "boolean" } } } } } }, "400": { "description": "Invalid request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/sessions": { "get": { "tags": [ "Auth" ], "summary": "List the signed-in user's browser sessions", "description": "Hosted browser-session (cookie) route backing the headless component and the documented-advanced non-Astro contract. Read-only; resolves the actor from the session cookie. The caller's current session is flagged.", "operationId": "listAuthAccountSessions", "security": [ { "browserSession": [] } ], "responses": { "200": { "description": "{ sessions: [{ session_id, current, ... }] }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/sessions/revoke": { "post": { "tags": [ "Auth" ], "summary": "Revoke one of the signed-in user's sessions", "description": "Hosted browser-session route (cookie + double-submit CSRF + same-origin). Revokes a single session by id, scoped to the actor (cannot revoke another user's session).", "operationId": "revokeAuthAccountSession", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ ok, revoked }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/sign-out-everywhere": { "post": { "tags": [ "Auth" ], "summary": "Revoke all of the user's sessions except the current one", "description": "Hosted browser-session route (cookie + double-submit CSRF + same-origin). Revokes every other session; the current session is preserved.", "operationId": "authAccountSignOutEverywhere", "security": [ { "browserSession": [] } ], "responses": { "200": { "description": "{ ok, revoked_count }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/password": { "post": { "tags": [ "Auth" ], "summary": "Set or change the signed-in user's password", "description": "Hosted browser-session route (cookie + double-submit CSRF + same-origin). Freshness step-up: the session must have authenticated within 5 minutes else R402_AUTH_FRESHNESS_REQUIRED. new_password is at most 72 bytes. On success the user's OTHER sessions are rotated.", "operationId": "setAuthAccountPassword", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_password" ], "properties": { "new_password": { "type": "string", "maxLength": 72 } } } } } }, "responses": { "200": { "description": "{ ok, sessions_revoked }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/passkeys/remove": { "post": { "tags": [ "Auth" ], "summary": "Remove one of the signed-in user's passkeys", "description": "Hosted browser-session route (cookie + double-submit CSRF + same-origin), freshness-gated (5-min step-up). User-scoped soft delete. Allow + warn: if removal leaves no Run402 password AND no remaining passkeys, the response carries a warning. To ADD a passkey use POST /auth/passkeys/register/{options,verify}.", "operationId": "removeAuthAccountPasskey", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "passkey_id" ], "properties": { "passkey_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ ok, removed, warning }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/account/identities/unlink": { "post": { "tags": [ "Auth" ], "summary": "Unlink a connected OAuth identity", "description": "Hosted browser-session route (cookie + double-submit CSRF + same-origin), freshness-gated (5-min step-up). Removes a linked OAuth identity (provider + provider subject) from the signed-in account and rotates other sessions on the change.", "operationId": "unlinkAuthAccountIdentity", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "provider", "subject" ], "properties": { "provider": { "type": "string" }, "subject": { "type": "string", "description": "The provider's subject id (provider_sub) of the identity to unlink." } } } } } }, "responses": { "200": { "description": "{ ok, unlinked }", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/magic-link/send": { "post": { "tags": [ "Auth" ], "summary": "Request hosted passwordless email sign-in", "description": "Hosted ceremony resolved by request host (no credential). delivery defaults to link; code/both returns an opaque challenge_id after accepted/captured delivery and HTML clients receive a same-tab confirmation form. Non-enumerating: acceptance never discloses whether the email maps to a user or claims provider delivery. Rate-limited per project/email/IP/tier.", "operationId": "hostedMagicLinkSend", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "return_to": { "type": "string", "description": "Relative path or same-origin URL to land on after sign-in. The hosted route continues to accept the legacy returnTo spelling for compatibility." }, "delivery": { "type": "string", "enum": [ "link", "code", "both" ], "default": "link" } } } } } }, "responses": { "200": { "description": "Generic accepted acknowledgement; code/both includes challenge_id only after accepted/captured delivery.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth/email-code/confirm": { "post": { "tags": [ "Auth" ], "summary": "Confirm a hosted email code", "description": "Same-origin hosted form/JSON ceremony. Resolves project, user, host, and return target from the challenge; caller-selected email, project, user, or redirect fields are rejected. Success sets the existing opaque host-only session cookie and returns 303 for forms or JSON for fetch clients.", "operationId": "hostedEmailCodeConfirm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "code" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } }, "additionalProperties": false } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "challenge_id", "code" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } } } } } }, "responses": { "200": { "description": "JSON success with redirect_to and Set-Cookie.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "redirect_to" ], "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "redirect_to": { "type": "string" } } } } } }, "303": { "description": "Form success; redirects to the challenge-bound return target and sets the session cookie." }, "400": { "description": "Malformed request or caller-selected identity/redirect field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "The well-formed code is invalid and the challenge still has attempts remaining.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "The hosted request failed same-origin enforcement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "The challenge is exhausted or otherwise terminal; request a fresh email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Project, IP, or challenge verification rate limit exceeded; Retry-After is returned and no code attempt is consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/passkeys/login/options": { "post": { "tags": [ "Auth" ], "summary": "Hosted WebAuthn login options", "description": "Hosted passkey-login ceremony, resolved by request host (no credential). Returns PublicKeyCredentialRequestOptionsJSON for navigator.credentials.get(). An email hint is accepted without exposing allowCredentials (enumeration-resistant).", "operationId": "hostedPasskeyLoginOptions", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "WebAuthn login options.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth/passkeys/login/verify": { "post": { "tags": [ "Auth" ], "summary": "Hosted WebAuthn login verify (mints the session cookie)", "description": "Hosted passkey-login ceremony terminal. Verifies the WebAuthn assertion, mints the browser-session cookie (amr: passkey) via Set-Cookie, and returns { ok, redirect_to } for the JS client to navigate. No JWT is issued — machine clients use /auth/v1/passkeys/login/verify.", "operationId": "hostedPasskeyLoginVerify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "response" ], "properties": { "challenge_id": { "type": "string" }, "response": { "type": "object" }, "return_to": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ ok, redirect_to } plus a Set-Cookie session.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth/passkeys/register/options": { "post": { "tags": [ "Auth" ], "summary": "Hosted WebAuthn registration options (signed-in user adds a passkey)", "description": "Hosted passkey-register ceremony for the cookie-authenticated actor (cookie + double-submit CSRF + same-origin). The user id is derived from the session, never the body. Returns PublicKeyCredentialCreationOptionsJSON.", "operationId": "hostedPasskeyRegisterOptions", "security": [ { "browserSession": [] } ], "responses": { "200": { "description": "WebAuthn registration options.", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/passkeys/register/verify": { "post": { "tags": [ "Auth" ], "summary": "Hosted WebAuthn registration verify (re-mints the session cookie)", "description": "Hosted passkey-register ceremony terminal for the cookie-authenticated actor (cookie + double-submit CSRF + same-origin). Verifies the registration, persists the passkey, and re-mints the session with amr: passkey (step-up).", "operationId": "hostedPasskeyRegisterVerify", "security": [ { "browserSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "response" ], "properties": { "challenge_id": { "type": "string" }, "response": { "type": "object" }, "label": { "type": "string" } } } } } }, "responses": { "200": { "description": "{ ok } plus a Set-Cookie session (amr: passkey).", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Health check (liveness only)", "description": "Unauthenticated liveness probe used by ALB and ECS. Returns 200 with `{\"status\":\"healthy\"}` when the gateway is up, 503 with `{\"status\":\"unhealthy\"}` when a critical dependency (postgres, postgrest) is down. Per-dependency state and the gateway version are intentionally NOT exposed here (GH-365); operators looking for that detail should use the admin-gated health-detail endpoint.", "operationId": "getHealth", "responses": { "200": { "description": "Gateway is up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "healthy" } } } } } }, "503": { "description": "Gateway cannot serve requests because a critical dependency is unreachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "unhealthy" } } } } } } } } }, "/health/storage": { "get": { "tags": [ "Health" ], "summary": "Storage-health signal (credential-free)", "description": "Unauthenticated, ungated boolean storage probe for the off-AWS status monitor. Returns 200 with `{\"status\":\"ok\"}` when the internal object-store probe succeeds, 503 with `{\"status\":\"error\"}` otherwise. The body is boolean-only and discloses NO architecture detail (no bucket name, no `checks` map, no version) — same anti-fingerprinting posture as the slim public /health.", "operationId": "getHealthStorage", "responses": { "200": { "description": "Storage is reachable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } }, "503": { "description": "Storage probe failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" } } } } } } } } }, "/human-identity-link-challenges/v1": { "post": { "tags": [ "Identity Links" ], "summary": "Begin a public human Buzz/Nostr identity link", "operationId": "createHumanIdentityLinkChallenge", "description": "Requires a direct Run402 human control-plane session and a fresh passkey. Explicitly discloses that completion publicly and durably correlates the human principal with the selected Buzz/Nostr identity. Creates only a five-minute challenge: no authenticator, membership, adoption, or organization authority.", "security": [ { "controlPlaneSession": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanIdentityLinkChallengeRequest" } } } }, "responses": { "200": { "description": "Exact idempotent challenge retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanIdentityLinkChallenge" } } } }, "201": { "description": "Five-minute public-correlation challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanIdentityLinkChallenge" } } } }, "400": { "description": "Invalid key, disclosure, visibility, or Idempotency-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Direct human session or fresh passkey required (IDENTITY_LINK_REQUIRES_HUMAN_SESSION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency or active Nostr-subject conflict (the conflicting principal is not disclosed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/human-identity-links/v1": { "post": { "tags": [ "Identity Links" ], "summary": "Complete a public human identity link with Buzz consent", "operationId": "completeHumanIdentityLink", "description": "Requires the same direct human session lineage, a fresh passkey, and the exact unexpired kind-24243 event returned by the released Buzz browser callback. The resulting public link is attribution only and creates no authenticator, membership, adoption, or organization authority.", "security": [ { "controlPlaneSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HumanIdentityLinkCompletionRequest" } } } }, "responses": { "200": { "description": "Exact event-id retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "201": { "description": "Public human identity link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "400": { "description": "Malformed request or callback event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Direct human session, exact lineage, or fresh passkey required (IDENTITY_LINK_REQUIRES_HUMAN_SESSION or IDENTITY_LINK_AUTHENTICATOR_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Expired, consumed, replayed, mismatched, or conflicting link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Buzz signature or exact challenge binding is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/identity-links/v1/challenges": { "post": { "tags": [ "Identity Links" ], "summary": "Begin a permanent-public Nostr identity-link proof", "operationId": "createNostrIdentityLinkChallenge", "description": "Requires a non-delegated SIWX EOA for a live agent principal and an Idempotency-Key. Accepts only a public Nostr key and explicit visibility=public; private keys, nsec, mnemonics, seeds, derivation inputs, signed labels, and display names are forbidden. The response authors the exact RFC 8785 payload. Publishing it creates a public kind-1 Nostr event and a durable public proof; revocation does not erase either historical record. Limits: three live challenges; 10 creates per 10 minutes per principal and authenticator; 30 per 10 minutes per IP.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkChallengeRequest" } } } }, "responses": { "200": { "description": "Exact idempotent retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkChallenge" } } } }, "201": { "description": "Challenge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkChallenge" } } } }, "400": { "description": "Strict JSON, canonicalization, public-disclosure, or Idempotency-Key failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Agent/non-delegated EOA requirement failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Idempotency, principal, or Nostr-subject conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "IDENTITY_LINK_RATE_LIMITED. Retry-After and details.retry_after_seconds are present.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Pre-launch challenge creation is disabled (IDENTITY_LINK_CAPABILITY_UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/identity-links/v1": { "post": { "tags": [ "Identity Links" ], "summary": "Complete a Nostr identity link with a dual-signature proof", "operationId": "completeNostrIdentityLink", "description": "Requires the exact agent principal and non-delegated SIWX EOA that created the challenge. The request body is parsed from preserved UTF-8 bytes with duplicate detection. The seven-field kind-1 event must contain the canonical two-field wrapper and either no tags or exactly one independently valid empty-condition NIP-OA owner-attestation tag. The Nostr link is public attribution only and is never authentication, authorization, ownership, payment authority, or a transfer target. Limits: five failed completions per challenge, 20 completions per 10 minutes per principal, and 60 per 10 minutes per IP.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkCompletionRequest" } } } }, "responses": { "200": { "description": "Exact event-id retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "201": { "description": "Identity link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "400": { "description": "Malformed outer JSON, duplicate/unknown field, or forbidden private-key-shaped input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Exact principal/authenticator changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Challenge expired, replay, or uniqueness conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Incomplete/noncanonical/tag-disallowed event or invalid dual proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "IDENTITY_LINK_RATE_LIMITED. Retry-After and details.retry_after_seconds are present.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Pre-launch or incident completion shutdown (IDENTITY_LINK_CAPABILITY_UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "Identity Links" ], "summary": "List the caller principal's retained identity-link history", "operationId": "listIdentityLinks", "description": "Returns active, revoked, and principal-inactive effective lifecycle state. It exposes no authenticator inventory, credential, wallet signature, or Nostr event; use the isolated public proof resource for independent verification.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque keyset cursor from next_cursor." } ], "responses": { "200": { "description": "Identity-link history page", "content": { "application/json": { "schema": { "type": "object", "required": [ "identity_links", "next_cursor" ], "properties": { "identity_links": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedIdentityRepresentation" } }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Invalid cursor or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/identity-links/v1/{identity_link_id}": { "delete": { "tags": [ "Identity Links" ], "summary": "Revoke a Nostr identity link", "operationId": "revokeIdentityLink", "description": "Idempotent. Requires any current non-delegated SIWX EOA of the linked principal. Revocation is append-only lifecycle state and does not erase the public event/proof or alter project ownership/authorization. Limited to 10 revocations per hour per principal. Once any public proof exists, this recovery path cannot be disabled by the routine rollout flag.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "identity_link_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^idlnk_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Revoked proof, or the original result on retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "403": { "description": "Current qualifying EOA required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found or not linked to this principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "IDENTITY_LINK_RATE_LIMITED. Retry-After and details.retry_after_seconds are present.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Pre-launch revocation capability is disabled; unavailable only while no public proof exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/identity-links/v1/admin/{identity_link_id}": { "delete": { "tags": [ "Identity Links" ], "summary": "Platform-security revoke an identity link", "operationId": "securityRevokeIdentityLink", "description": "High-severity, audited platform-admin revocation only. It cannot create, move, or reactivate a link.", "security": [ { "adminKey": [] } ], "parameters": [ { "name": "identity_link_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^idlnk_[0-9a-f]{32}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason_code" ], "properties": { "reason_code": { "type": "string", "enum": [ "credential_compromise", "security_response" ] } } } } } }, "responses": { "200": { "description": "Revoked public proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "400": { "description": "Invalid reason code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Identity link not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/identity-link-proofs/v1/{identity_link_id}": { "get": { "tags": [ "Identity Links" ], "summary": "Independently verify a public identity-link proof", "operationId": "getPublicIdentityLinkProof", "description": "Intentionally unauthenticated and authentication-invariant. Returns only immutable public proof bytes and lifecycle state. Cache-Control is no-store so revocation is visible; missing and malformed ids use the same non-revealing 404. Limited to 120 reads per minute per IP. Once any public proof exists, this route cannot be disabled by the routine rollout flag.", "security": [], "parameters": [ { "name": "identity_link_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^idlnk_[0-9a-f]{32}$" } } ], "responses": { "200": { "description": "Public proof", "headers": { "Cache-Control": { "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLinkProof" } } } }, "404": { "description": "Proof not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "IDENTITY_LINK_RATE_LIMITED. Retry-After and details.retry_after_seconds are present.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Pre-launch public-proof capability is disabled; unavailable only while no public proof exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/whoami": { "get": { "tags": [ "Org" ], "summary": "Resolve the caller's control-plane principal, memberships, and Buzz lifecycle state", "operationId": "whoami", "description": "SIWX, a control-plane session, or a scoped delegate bearer authenticates the caller and returns the resolved principal, active org memberships, and independent Buzz adoption/installation/enrollment eligibility and drift. A wallet and a Buzz proof are authenticators or attribution evidence, never owners by themselves. A delegate resolves to its own subject principal (typically with no memberships of its own, since a delegate acts via a project_grant rather than membership) — resolving your own identity actuates and leaks nothing beyond it, so this is delegate-capable the same way the cold-restart-recovery `POST /projects/v1/:project_id/tokens` is.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] }, { "delegateBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "200": { "description": "Resolved principal + memberships", "content": { "application/json": { "schema": { "type": "object", "required": [ "principal", "active_authenticator", "linked_identities", "authenticator_id", "memberships", "buzz" ], "properties": { "principal": { "type": "object", "nullable": true }, "active_authenticator": { "allOf": [ { "$ref": "#/components/schemas/ActiveAuthenticatorRepresentation" } ], "nullable": true, "description": "Only the authenticator used for this request; never an authenticator inventory." }, "linked_identities": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedIdentityRepresentation" }, "description": "Current public attribution links. These do not authorize or own resources." }, "authenticator_id": { "type": "string", "nullable": true, "description": "Legacy sibling retained unchanged; equals active_authenticator.authenticator_id when present." }, "memberships": { "type": "array", "items": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "billing", "viewer" ] }, "status": { "type": "string" } } } }, "buzz": { "$ref": "#/components/schemas/BuzzPrincipalStatus", "description": "Four independent lifecycle surfaces. Skill installation remains client-managed and inert; no Buzz proof is converted into Run402 authority." }, "encryption_key": { "type": "object", "nullable": true, "description": "gitvault-agent-envelopes D3: the principal's CURRENT gitvault directory key (pending or active) — metadata only, never key material. `null` = none published; the SDK's enroll-if-absent step keys off this.", "properties": { "encryption_key_id": { "type": "string", "format": "uuid" }, "ek_fingerprint": { "type": "string" }, "custody_scheme": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "active" ] }, "created_at": { "type": "string", "format": "date-time" }, "signing_fingerprint": { "type": "string", "nullable": true, "description": "gitvault-multi-writer rev 47. The principal's OPTIONAL vault-writer signing half — `vk_<32 hex>`, or `null` if never published. Never the raw `signing_pubkey`, mirroring this endpoint's existing encryption-half minimalism." }, "signing_possession_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "gitvault-multi-writer rev 47. When `signing_fingerprint`'s `possession_signature` was verified; `null` alongside a `null` `signing_fingerprint`." } } } } } } } } } } }, "/agent/v1/lightning-wallet": { "post": { "tags": [ "Billing" ], "summary": "Mint the caller's Lightning wallet (the Lightning allowance)", "operationId": "mintAgentLightningWallet", "description": "Asks the platform for one budgeted, isolated Lightning sub-wallet on Run402's own Hub for the calling agent principal (`run402 init lightning`). Idempotent per principal: a live wallet is returned as is and nothing is minted twice. The platform-side broker mints the sub-wallet, so the first call usually answers `202` with `status: \"minting\"`; poll `GET /agent/v1/lightning-wallet`. The one response that first observes the wallet `active` carries `pairing` (the NWC pairing URI, a bearer secret shown exactly once and never recoverable); every later response reports `has_pairing` only. Custody is the platform Hub (`custody: \"run402_hub\"`): the sats sit on Run402's Hub and the agent holds a budgeted connection. `budget_sats` is the platform-set spending cap and `starter_sats` the amount the platform funded at mint.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "201": { "description": "The wallet is active and this response hands out the pairing secret, exactly once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "200": { "description": "The wallet exists (replay); no pairing is included.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "202": { "description": "The platform is minting the wallet; poll the GET route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "description": "`LIGHTNING_WALLET_NOT_AVAILABLE` — the platform Hub is not configured or not ready; pay over x402 from the Base allowance meanwhile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "get": { "tags": [ "Billing" ], "summary": "Read the caller's Lightning wallet", "operationId": "getAgentLightningWallet", "description": "The wallet's public facts. `202` while it is still minting. The first read of an active wallet whose pairing was never handed out answers `201` with `pairing` (once); later reads answer `200` with `has_pairing: true` and no secret.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "200": { "description": "The wallet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "201": { "description": "The wallet, carrying the pairing secret exactly once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "202": { "description": "Still minting.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`LIGHTNING_WALLET_NOT_FOUND` — the caller has no live wallet; mint one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "delete": { "tags": [ "Billing" ], "summary": "Revoke the caller's Lightning wallet", "operationId": "revokeAgentLightningWallet", "description": "Revocation is deletion of the sub-wallet on the platform Hub: the pairing stops paying and the wallet's balance returns to the platform. The principal, its Base allowance, and its organizations are unchanged; a revoked principal may mint again once the deletion completes.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "202": { "description": "Revocation accepted (`status: \"revoking\"`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentLightningWallet" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "`LIGHTNING_WALLET_NOT_FOUND` — nothing to revoke.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/me": { "patch": { "tags": [ "Org" ], "summary": "Set the caller's own display name", "operationId": "setMyDisplayName", "description": "Sets `display_name` on the calling principal (1–64 characters after trimming, no control characters) and returns the same body `GET /agent/v1/whoami` returns. Self-only: a delegate sets the name of the principal it acts for, never a name of its own. This name is what promotion credit (`hand_to_operator.credited_as`), `run402 up`'s room presence, and audit surfaces show for the principal; `run402 init --name`, `run402 org whoami --set-name`, and `up`'s agent-principal-only default (`RUN402_AGENT_NAME` when the runtime declares one, else a specifically detected client: `claude-code`, `codex`, `cursor`, `grok`; nothing is written when nothing is known) all land here. Wallet principals are created unnamed: the gateway never seeds `display_name` from the wallet subject.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] }, { "delegateBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "type": "string", "minLength": 1, "maxLength": 64, "example": "Grok" } } } } } }, "responses": { "200": { "description": "The updated principal in the `whoami` body shape.", "content": { "application/json": { "schema": { "type": "object", "required": [ "principal" ], "properties": { "principal": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "display_name": { "type": "string", "nullable": true } }, "additionalProperties": true } }, "additionalProperties": true } } } }, "400": { "description": "`INVALID_DISPLAY_NAME` — empty, over 64 characters, or contains control characters; `details` carries `min` and `max`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/agent/v1/whoami/encryption-key": { "post": { "tags": [ "Org" ], "summary": "Publish the caller's own gitvault directory key (human or agent principal)", "operationId": "publishWhoamiEncryptionKey", "description": "Self-only, custody-eligible principals only (`human` | `agent`; a `ci` caller is refused NOT_A_RECIPIENT_PRINCIPAL): publishes the caller's own X25519 public key + `ek_` fingerprint to the org-scoped encryption-key directory (gitvault-human-envelopes, widened by gitvault-agent-envelopes). The private key never reaches the gateway. `custody_scheme: keystore_v1` is the CLI keystore's own key (no wrappers — the keystore file is the custody): the row is created PENDING and the response carries `activation` (an ECDH possession challenge) — answer it on `POST /agent/v1/whoami/encryption-key/activate`; a pending key is a recipient nowhere. Republishing the principal's CURRENT key is an idempotent 200 (`deduplicated: true`). A DIFFERENT key is refused 409 KEY_ROTATION_REQUIRED — rotation is never automatic (a stolen wallet key must not replace a member's decryption identity); remedies: restore the keystore backup, have an org owner revoke the stale key (`DELETE /orgs/v1/:org_id/members/:principal_id/encryption-key`), or — only for a principal that is the sole custody-eligible member of every org it belongs to — republish with `replace_current: true` (otherwise 403 KEY_ROTATION_NOT_SELF_AUTHORIZABLE). Credential-gated: SIWX or a control-plane session only — a delegate bearer, CI session, service key, or admin key never reaches this route. The SDK runs this automatically on the first gitvault operation of a keystore with no published key (`run402 repos …`, `git clone`/`push`); there is no enrollment verb.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_key": { "type": "string", "description": "Canonical base64url-encoded 32-byte X25519 public key." }, "ek_fingerprint": { "type": "string", "description": "`ek_<32 hex>` — first 16 bytes of SHA-256(raw pubkey)." }, "suite": { "type": "string", "description": "Defaults to `r402s-1`." }, "key_id": { "type": "string", "format": "uuid", "description": "Client-minted key row UUID — required when `wrappers[]` is supplied (it is bound inside every wrapper's sealed context)." }, "custody_scheme": { "type": "string", "enum": [ "legacy_direct_prf_v1", "wrapped_legacy_scalar_v1", "wrapped_random_v1", "keystore_v1" ], "description": "EXPLICIT custody declaration (consult round 1: never inferred from wrapper count). `keystore_v1` — the CLI keystore's key, no wrappers, pending until the possession proof; `wrapped_*` require `wrappers[]`; omit for a legacy direct-PRF browser enrollment." }, "wrappers": { "type": "array", "description": "Wrappers created ATOMICALLY with the key row, all PENDING — the key activates only when its first wrapper passes the possession-proof activation. Same item shape as `POST /agent/v1/source-access/wrappers`.", "items": { "type": "object", "properties": { "wrapper_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "webauthn_prf", "recovery_code" ] }, "wrapper_ciphertext": { "type": "string" }, "elevation_id": { "type": "string", "format": "uuid" } }, "required": [ "wrapper_id", "kind", "wrapper_ciphertext" ] } }, "replace_current": { "type": "boolean", "description": "gitvault-agent-envelopes D3: replace a DIFFERENT current key. Honored only when the caller is the sole custody-eligible member of every org it belongs to; otherwise 403 KEY_ROTATION_NOT_SELF_AUTHORIZABLE. Never implied." }, "signing_pubkey": { "type": "string", "description": "gitvault-multi-writer rev 47. Canonical base64url-encoded 32-byte Ed25519 public key — the vault-WRITER signing half, unrelated to `public_key` above (the encryption half). OPTIONAL, and ALL-OR-NONE with `signing_fingerprint`/`possession_signature`: omitting all three publishes only the encryption half, byte-identical to a pre-rev-47 client." }, "signing_fingerprint": { "type": "string", "description": "gitvault-multi-writer rev 47. `vk_<32 hex>` derived from `signing_pubkey` via the same `keyFingerprint` convention `add_writer_key`/p0062 use — a self-consistency check, not a separate derivation. Mismatched against a re-derivation from `signing_pubkey` → 400 VALIDATION_FAILED naming `possession_signature`." }, "possession_signature": { "type": "string", "description": "gitvault-multi-writer rev 47. Ed25519 signature over `JCS{domain:\"r402s/v0/signing-key-possession/v1\", principal_id, signing_pubkey, encryption_pubkey}`, verified SYNCHRONOUSLY under `signing_pubkey` — no challenge round-trip, since a valid signature already IS possession. The signing half is NEVER rotation-gated: publishing a new signing key grants nothing by itself (becoming a vault writer still needs an existing writer's cooperation or a handoff grant+acceptance), so there is no `KEY_ROTATION_REQUIRED` analog here." } }, "required": [ "public_key", "ek_fingerprint" ] } } } }, "responses": { "201": { "description": "Key published — `state: pending` for `keystore_v1` (answer `activation` on `/activate`) or when wrappers were supplied (activate the first wrapper); `active` for a legacy direct-PRF publish. A 200 with `deduplicated: true` means the submitted key already IS the principal's current key (no write).", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "encryption_key_id": { "type": "string", "format": "uuid" }, "ek_fingerprint": { "type": "string" }, "suite": { "type": "string" }, "custody_scheme": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "active" ] }, "created_at": { "type": "string", "format": "date-time" }, "signing_fingerprint": { "type": "string", "nullable": true, "description": "gitvault-multi-writer rev 47. `vk_<32 hex>` for the signing half just published/refreshed, or the principal's existing one if this call omitted the signing fields entirely (byte-identical to a pre-rev-47 response, and `null` if no signing half has ever been published). Never the raw `signing_pubkey`." }, "signing_possession_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "gitvault-multi-writer rev 47. Timestamp the `possession_signature` was verified — synchronous with this call, so equal to `created_at`/now on a fresh signing-half publish; carried forward unchanged when this call didn't touch the signing half." }, "wrapper_activations": { "type": "array", "description": "One ECDH possession challenge per created wrapper (see the activate route).", "items": { "type": "object", "properties": { "wrapper_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "challenge_id": { "type": "string", "format": "uuid" }, "epk": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "deduplicated": { "type": "boolean", "description": "True when the publish matched the principal's current key exactly and nothing was written." }, "activation": { "type": "object", "nullable": true, "description": "`keystore_v1` only: the key-level ECDH possession challenge. `proof = base64url(HMAC-SHA256(X25519(keystore_private, epk), \"r402s/v0/keystore-key-possession/v1\\n\" + JCS{challenge_id, encryption_key_id, public_key}))`.", "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "epk": { "type": "string", "description": "Server ephemeral X25519 public key, base64url." }, "expires_at": { "type": "string", "format": "date-time" } } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "description": "VALIDATION_FAILED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "NOT_A_RECIPIENT_PRINCIPAL (a `ci` principal) or KEY_ROTATION_NOT_SELF_AUTHORIZABLE (`replace_current` by a principal that shares an org with another custody-eligible member).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "KEY_ROTATION_REQUIRED — the principal already has a published key that differs from the one submitted; rotation is never automatic. `details` names both fingerprints and the remedies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/orgs/v1/{org_id}/encryption-keys": { "get": { "tags": [ "Org" ], "summary": "Read the org's encryption-key directory", "operationId": "listOrgEncryptionKeys", "description": "The org's directory of envelope-capable principals (gitvault-human-envelopes design D7): every active human member with a published key. Readable by any active member; an admin key reads too. Public-key material only — reads stay authorized to avoid a directory-harvest surface.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] }, { "adminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The directory", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "principal_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "public_key": { "type": "string", "description": "The raw 32-byte X25519 public key, base64url-encoded, no padding — what a client wraps K_repo to (paired with ek_fingerprint, its identity)." }, "ek_fingerprint": { "type": "string" }, "suite": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "signing_pubkey": { "type": "string", "nullable": true, "description": "gitvault-multi-writer rev 47. Canonical base64url-encoded 32-byte Ed25519 public key — this principal's OPTIONAL vault-writer signing half, or `null` if never published. Unlike `whoami`, the directory exposes the FULL key (not just its fingerprint): a client deciding who to add as a vault writer needs the real key." }, "signing_fingerprint": { "type": "string", "nullable": true, "description": "gitvault-multi-writer rev 47. `vk_<32 hex>` derived from `signing_pubkey`; `null` alongside a `null` `signing_pubkey`." }, "signing_possession_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "gitvault-multi-writer rev 47. When this principal's `possession_signature` for the signing half was verified; `null` alongside a `null` `signing_pubkey`." } } } } } } } } }, "403": { "description": "Not a member of this org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/operator/claim-wallet-org/challenge": { "post": { "tags": [ "Org" ], "summary": "Issue a wallet-org claim challenge (first-class-orgs)", "operationId": "claimWalletOrgChallenge", "description": "Issues a single-use nonce the wallet must sign to claim the org it owns into the caller's human identity. Reveals nothing about the wallet's orgs (control is proven only at claim time). Requires a control-plane session (auth only — no step-up; step-up is enforced on the claim itself).", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "description": "0x EVM address of the wallet whose org is being claimed." } } } } } }, "responses": { "201": { "description": "The challenge nonce to sign", "content": { "application/json": { "schema": { "type": "object", "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "nonce": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "wallet must be a 0x EVM address (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/operator/claim-wallet-org": { "post": { "tags": [ "Org" ], "summary": "Claim a wallet-owned org (first-class-orgs, Phase 1.5)", "operationId": "claimWalletOrg", "description": "Become the OWNER of an org currently owned by your wallet's agent principal — an ownership transfer on org memberships, not a credential link. DUAL PROOF: the control-plane session (request auth) + a fresh action-bound SIWX signature from the wallet sent as the SIGN-IN-WITH-X header (carrying the challenge nonce). The wallet authenticator stays on the agent; the agent is downgraded owner→developer. If the wallet's agent owns more than one org, returns { status: 'select_org', selectable_orgs } until org_id is chosen.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "Required only when the wallet's agent owns more than one claimable org." }, "display_name": { "type": "string", "nullable": true, "description": "Optional label to set on the claimed org." } } } } } }, "responses": { "200": { "description": "Claimed, or a select_org prompt for a multi-org wallet", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "claimed", "select_org" ] }, "org_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "role": { "type": "string" }, "already_owned": { "type": "boolean" }, "selectable_orgs": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing/invalid/replayed wallet proof or challenge", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Nothing claimable for this wallet proof (CLAIM_NOTHING_TO_CLAIM — non-revealing)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Complex source, self-claim, or free-org cap exceeded", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orgs/v1": { "get": { "tags": [ "Org" ], "summary": "List orgs the caller is an active member of (v1.77)", "operationId": "listOrgs", "description": "Orgs (organizations) on which the authenticated principal holds an active membership, with role.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "200": { "description": "The caller's orgs", "content": { "application/json": { "schema": { "type": "object", "properties": { "orgs": { "type": "array", "items": { "type": "object" } } } } } } } } }, "post": { "tags": [ "Org" ], "summary": "Create an organization (first-class-orgs)", "operationId": "createOrg", "description": "Creates an empty org on the perpetual prototype tier (kygit-handoff D4 — one x402 payment, never expires, never scheduler-advanced); the caller becomes owner. Not owner-gated (no org exists yet) — requires an authenticated principal + a fresh step-up + the soft per-owner free-org cap. Accepts ONLY display_name; a tier (or any other) field is rejected. Returns the org summary including persisted tier/lease state.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "nullable": true, "description": "Optional org label (max 100 chars, NFC-normalized, non-unique, never authoritative)." } } } } } }, "responses": { "201": { "description": "The created org", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "slug": { "type": [ "string", "null" ], "description": "The org's claimable, address-form handle (repo-first-onramp D6). Distinct from display_name; null if unclaimed." }, "tier": { "type": [ "string", "null" ] }, "lease_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease began. Null only for a pre-subscription placeholder org." }, "lease_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease expires. Null only for a pre-subscription placeholder org." } } } } } }, "400": { "description": "Unsupported field (e.g. tier) or invalid display_name (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "FREE_ORG_OWNER_LIMIT_EXCEEDED", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orgs/v1/{org_id}": { "get": { "tags": [ "Org" ], "summary": "Get one org (first-class-orgs)", "operationId": "getOrg", "description": "The org's label, tier lease state, and the caller's role. Any active member may view. Authorize-before-reveal: a non-member (incl. a guessed id) gets the same 403 as a real-but-unauthorized org.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The org", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "slug": { "type": [ "string", "null" ], "description": "The org's claimable, address-form handle (repo-first-onramp D6). Distinct from display_name; null if unclaimed." }, "tier": { "type": [ "string", "null" ] }, "lease_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease began. Null only for a pre-subscription placeholder org." }, "lease_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease expires. Null only for a pre-subscription placeholder org." }, "role": { "type": "string", "nullable": true } } } } } }, "403": { "description": "Not a member of this org (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "patch": { "tags": [ "Org" ], "summary": "Rename an org (first-class-orgs)", "operationId": "renameOrg", "description": "Owner-only; sets or clears the org's display_name (null or empty string clears) and returns the updated org summary including tier lease state. Step-up gated. Authorize-before-reveal on a non-owner (incl. a guessed id).", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "display_name" ], "properties": { "display_name": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "The updated org", "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string", "nullable": true }, "slug": { "type": [ "string", "null" ], "description": "The org's claimable, address-form handle (repo-first-onramp D6). Distinct from display_name; null if unclaimed." }, "tier": { "type": [ "string", "null" ] }, "lease_started_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease began. Null only for a pre-subscription placeholder org." }, "lease_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp when the current lease expires. Null only for a pre-subscription placeholder org." } } } } } }, "403": { "description": "Owner role required (FORBIDDEN) — also returned for a guessed id", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orgs/v1/{org_id}/slug": { "post": { "tags": [ "Org" ], "summary": "Claim or rename the org's slug (repo-first-onramp D6)", "operationId": "claimOrgSlug", "description": "Owner-only. Claims a globally-unique, address-form slug for the org (`run402::/`), distinct from display_name. A genesis claim (the org had no slug yet) is a 201; a rename (the org already had a slug — the old one releases into a ~90-day cooldown behind a typed SLUG_RELEASED refusal, never a redirect) is a 200. The org's FIRST-EVER slug claim is free — no billing wallet required; every later claim or rename debits a one-time payable claim fee from the org's allowance. `fee_usd_micros` in the response names the real price of THIS call (0 or the fee). Requires Idempotency-Key so a retried claim cannot double-bill. Refused for names on the static reserved list (SLUG_RESERVED) or the curated protected-brands list (SLUG_PROTECTED, claimable only via manual review), and for a slug already claimed or in cooldown (SLUG_TAKEN / SLUG_RELEASED, the latter naming the successor slug).", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Required — a paid, side-effecting claim. An exact retry with the same key never double-bills." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "description": "Lowercase [a-z0-9-], no leading/trailing/double hyphen, at most 39 characters. Case-folded at resolution; uppercase is refused at claim time, not silently normalized." } } } } } }, "responses": { "200": { "description": "Renamed — the org already held a different slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSlugClaimResult" } } } }, "201": { "description": "Genesis claim — the org had no slug yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSlugClaimResult" } } } }, "400": { "description": "Grammar violation (VALIDATION_FAILED) or missing Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID)", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Owner role required (FORBIDDEN); reserved (SLUG_RESERVED); protected brand (SLUG_PROTECTED); insufficient balance (INSUFFICIENT_BALANCE, names required_usd_micros — never returned for an org's free first-ever claim); no billing wallet (ORG_HAS_NO_BILLING_WALLET, names required_usd_micros — never returned for an org's free first-ever claim)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Already claimed by another org (SLUG_TAKEN), or in cooldown naming the successor (SLUG_RELEASED)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orgs/v1/{org_id}/members": { "get": { "tags": [ "Org" ], "summary": "List org members (v1.77)", "operationId": "listOrgMembers", "description": "Lists the org's members (principal, role, status, representative wallet). Any active member may view.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Members of the org", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "description": "Not a member of this org (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "tags": [ "Org" ], "summary": "Add an org member by wallet (owner-only, v1.77)", "operationId": "addOrgMember", "description": "Owner-only. Adds a member by wallet address with a role. A brand-new wallet is provisioned as a `human` principal; an existing wallet is added by its resolved principal regardless of `type` (informational, not an authz gate). For non-member automation, prefer a per-project grant. Audited. gitvault-agent-envelopes: custody follows membership for `human` and `agent` principals alike — the member becomes a desired envelope recipient on every present and future vault the org owns (a `ci` principal does not), and the cap on custody-eligible memberships (MAX_EPOCH_ROTATION_ENVELOPES) is reserved at this add, keyed or not (422 MAX_EPOCH_ROTATION_ENVELOPES_EXCEEDED). gitvault-multi-writer rev 47: `next_actions` additionally carries a `sync_writers` entry naming the org's vaults where the new member is NOT yet an active, non-gateway-blocked writer — the signal to run `add_writer_key{\"writer\"}` (or `repos access sync`) for them; omitted when there is no such vault. No server-side writer admission ever happens on this route.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "billing", "viewer" ], "default": "developer" } } } } } }, "responses": { "201": { "description": "Member added", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "principal_id": { "type": "string", "format": "uuid" }, "role": { "type": "string" }, "envelope": { "type": "object", "description": "gitvault-agent-envelopes D6: the new member's vault-custody state. `enrolled_pending_wrap` — an active key; a key-holder's next gitvault operation wraps each vault to it. `not_enrolled` — the MEMBER's next gitvault operation enrolls its keystore key (nothing is asked of the owner). `not_applicable` — a `ci` principal.", "properties": { "state": { "type": "string", "enum": [ "enrolled_pending_wrap", "not_enrolled", "not_applicable" ] }, "ek_fingerprint": { "type": "string", "nullable": true } } }, "next_actions": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "GITVAULT_BYO_SINGLE_WRITER \u2014 this organization owns a bring-your-own-bucket vault, which admits exactly one writer in v1 (its key envelopes live only in the customer's bucket). A developer+ add is refused by name, naming the vault in details: { storage_profile: \"byo\", vault_id, org_id }; no membership row, target org-of-one, or audit row is written. A viewer/billing add is unaffected \u2014 those roles confer no writer eligibility.", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/orgs/v1/{org_id}/members/{principal_id}": { "patch": { "tags": [ "Org" ], "summary": "Change a member's role (owner-only, v1.77)", "operationId": "changeOrgMemberRole", "description": "Owner-only. Changes a member's role. The org always keeps ≥1 active owner (LAST_OWNER guard). Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "developer", "billing", "viewer" ] } } } } } }, "responses": { "200": { "description": "Role changed", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Cannot demote the last active owner (LAST_OWNER)", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "Org" ], "summary": "Revoke an org member (owner-only, v1.77)", "operationId": "revokeOrgMember", "description": "Owner-only. Revokes a member (status='revoked', a single row, no key rotation, ownership unchanged). The org always keeps ≥1 active owner (LAST_OWNER guard). Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "principal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Member revoked", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "Cannot revoke the last active owner (LAST_OWNER)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/projects/v1/{project_id}/grants": { "post": { "tags": [ "Org" ], "summary": "Issue a project grant (owner-only, v1.77)", "operationId": "issueProjectGrant", "description": "Owner-only on the project's owning org. Issues a capability grant (e.g. `deploy`, `functions:write`) to a wallet's principal — the delegation mechanism for agent/ci principals. Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet", "capability" ], "properties": { "wallet": { "type": "string" }, "capability": { "type": "string", "example": "functions:write" }, "policy": { "type": "object" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "responses": { "201": { "description": "Grant issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "grant_id": { "type": "string", "format": "uuid" }, "principal_id": { "type": "string", "format": "uuid" } } } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/projects/v1/{project_id}/grants/{grant_id}": { "delete": { "tags": [ "Org" ], "summary": "Revoke a project grant (owner-only, v1.77)", "operationId": "revokeProjectGrant", "description": "Owner-only on the project's owning org. Revokes a grant (revoked_at set). Takes effect immediately for subsequent requests. Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Grant revoked", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No active grant with that id on this project (GRANT_NOT_FOUND)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/projects/v1/{project_id}/delegates": { "post": { "tags": [ "Delegates" ], "summary": "Issue a delegate (owner-only, v1.78)", "operationId": "issueDelegate", "description": "Owner-only on the project's owning org. Mints a scoped, capped, expiring, revocable credential for an agent/ci principal carrying a project_grant's authority (NARROWED by `scope`/`spend_cap`/`expires_at` — never widened). A delegate is never an owner. For `kind: run402_agent_key` the response `token` (the bearer to hand the agent) is returned ONCE. Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "grant_id", "kind", "scope" ], "properties": { "grant_id": { "type": "string", "format": "uuid", "description": "The project_grant whose authority this delegate carries." }, "kind": { "type": "string", "enum": [ "tempo_access_key", "base_disposable_eoa", "run402_agent_key", "ci_oidc" ], "description": "erc7710 is forward-declared and rejected (501)." }, "scope": { "type": "object", "required": [ "v", "capabilities" ], "properties": { "v": { "type": "integer", "enum": [ 1 ] }, "capabilities": { "type": "array", "items": { "type": "string" } }, "projects": { "type": "array", "items": { "type": "string" } } } }, "spend_cap": { "type": "object", "nullable": true, "description": "Required for payment rails (tempo/base). usd_micros.", "properties": { "v": { "type": "integer", "enum": [ 1 ] }, "currency": { "type": "string", "enum": [ "usd_micros" ] }, "period": { "type": "string", "enum": [ "day", "week", "month" ] }, "per_period": { "type": "integer" }, "per_tx": { "type": "integer" } } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "public_subject": { "type": "string" } } } } } }, "responses": { "201": { "description": "Delegate issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "delegate_id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "nullable": true, "description": "run402_agent_key bearer — returned once." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "403": { "description": "Owner role required (FORBIDDEN)", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "Delegates" ], "summary": "List a project's delegates (owner-only, v1.78)", "operationId": "listProjectDelegates", "description": "Owner-only. Returns delegate names, kind, scope, and spend_cap — NEVER `encrypted_secret_ref` or a token.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delegate list", "content": { "application/json": { "schema": { "type": "object", "properties": { "delegates": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/projects/v1/{project_id}/delegates/{delegate_id}": { "delete": { "tags": [ "Delegates" ], "summary": "Revoke a delegate (owner-only, v1.78)", "operationId": "revokeDelegate", "description": "Owner-only. Sets `revoked_at`; immediate for subsequent requests. For base_disposable_eoa, refills stop and a sweep is attempted (on-chain bare-key risk is bounded to the prefunded balance). Audited.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delegate_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delegate revoked", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No active delegate with that id (DELEGATE_NOT_FOUND)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/projects/v1/{project_id}/delegates/{delegate_id}/rotate": { "post": { "tags": [ "Delegates" ], "summary": "Rotate a delegate (owner-only, v1.78)", "operationId": "rotateDelegate", "description": "Owner-only. Revokes the current delegate and issues a fresh one with the same principal/grant/kind/scope/cap/expiry. Returns the new delegate (and, for run402_agent_key, a fresh token).", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delegate_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Delegate rotated", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "No active delegate with that id (DELEGATE_NOT_FOUND)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/ping/v1": { "get": { "tags": [ "Health" ], "summary": "Authenticated ping (wallet auth)", "operationId": "ping", "description": "Health probe that verifies wallet auth is working. Free within tier.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "200": { "description": "Ping accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "paid": { "type": "boolean", "example": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/.well-known/x402": { "get": { "tags": [ "Health" ], "summary": "x402 resource discovery", "operationId": "x402Discovery", "description": "Lists paid resources plus explicitly described payment capabilities, including the exact Run402 MPP Lightning charge profile on Bitcoin mainnet.", "responses": { "200": { "description": "x402 resource list", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "resources", "mppResources" ], "properties": { "version": { "type": "integer", "example": 1 }, "description": { "type": "string" }, "instructions": { "type": "string" }, "resources": { "type": "array", "description": "x402-gated resource URIs", "items": { "type": "string", "format": "uri" } }, "mppResources": { "type": "array", "description": "MPP-gated resource URIs", "items": { "type": "string", "format": "uri" } }, "paymentCapabilities": { "type": "array", "items": { "type": "object", "required": [ "protocol", "method", "intent", "profile", "network", "resources", "activation" ], "properties": { "protocol": { "type": "string", "enum": [ "mpp" ] }, "method": { "type": "string", "enum": [ "lightning" ] }, "intent": { "type": "string", "enum": [ "charge" ] }, "profile": { "type": "string", "enum": [ "run402-mpp-lightning-charge-draft00-safety-v1" ] }, "network": { "type": "string", "enum": [ "mainnet" ] }, "resources": { "type": "array", "items": { "type": "string", "format": "uri" } }, "activation": { "type": "string", "enum": [ "active" ] } } } } } } } } } } } }, "/tiers/v1": { "get": { "tags": [ "Tiers" ], "summary": "List tier pricing", "operationId": "listTiers", "description": "Returns available tiers, pricing, and resource limits. No auth required. Useful for programmatic price discovery before subscribing.", "responses": { "200": { "description": "Tier pricing and auth info", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "$ref": "#/components/schemas/TierPricing" }, "auth": { "type": "object", "properties": { "method": { "type": "string", "example": "SIWX (CAIP-122 / EIP-4361) via SIGN-IN-WITH-X header" }, "headers": { "type": "array", "items": { "type": "string" }, "example": [ "SIGN-IN-WITH-X" ] }, "message_format": { "type": "string", "example": "base64(JSON CAIP-122 payload with domain, issuedAt, expirationTime, and signature)" } } } } } } } } } } }, "/tiers/v1/{tier}": { "post": { "tags": [ "Tiers" ], "summary": "Subscribe, renew, or upgrade tier", "operationId": "setTier", "description": "Unified tier endpoint. Auto-detects subscribe, renew, or upgrade; downgrading during an active lease is rejected. Existing x402 behavior remains compatible. The explicit MPP Lightning charge path requires Run402-Payment-Profile: run402-mpp-lightning-charge-draft00-safety-v1, Accept-Payment selecting lightning/charge, exactly one supported principal credential, and one stable Idempotency-Key. It returns one fresh fixed-amount Bitcoin-mainnet BOLT11 invoice per emitted challenge, retains quote metadata, and requires exact-request reconciliation after possible dispatch.", "x-payment-info": { "protocols": [ "x402", "mpp", "mpp-lightning-charge" ], "price": { "mode": "dynamic", "currency": "USD", "min": "0.10", "max": "20.00" } }, "security": [ { "x402": [] }, { "walletAuth": [], "mppPayment": [] } ], "parameters": [ { "name": "tier", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "prototype", "hobby", "team" ] } }, { "name": "Run402-Payment-Profile", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "run402-mpp-lightning-charge-draft00-safety-v1" ] }, "description": "Exact opt-in for the draft-pinned MPP Lightning charge profile. Omit for existing payment behavior." }, { "name": "Accept-Payment", "in": "header", "required": false, "schema": { "type": "string" }, "example": "lightning/charge;q=1.000, tempo/charge;q=0.999, x402/charge;q=0.998", "description": "Ordered payment capabilities. Lightning is selected only when it is the highest-quality supported match." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Required for the explicit Lightning profile. Exact retries preserve the retained payment intent and committed tier result." } ], "responses": { "200": { "description": "Tier renewed or upgraded — OR, for `prototype` on an organization that already holds perpetual prototype, a short-circuit before the paywall (kygit-handoff D4/D5): no 402 challenge is answered, no payment is verified or settled, no ledger row is written. Paying twice is not charged twice.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TierSubscription" }, { "$ref": "#/components/schemas/MppLightningTierResult" }, { "$ref": "#/components/schemas/TierAlreadyActive" } ] } } } }, "201": { "description": "Tier subscribed (new subscription)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/TierSubscription" }, { "$ref": "#/components/schemas/MppLightningTierResult" } ] } } } }, "400": { "description": "Cannot downgrade during active lease", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "409": { "description": "The retained Lightning intent is pending, in recovery, credited, or conflicts with the supplied request. No new actionable payment offer is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Lightning quote, invoice issuance, node observation, or retained payment state is temporarily unavailable. Retry only the identical request as directed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/tiers/v1/status": { "get": { "tags": [ "Tiers" ], "summary": "Get wallet tier status", "operationId": "getTierStatus", "description": "Returns the wallet's current tier, lease expiry, and resource pool usage. Requires wallet auth.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "responses": { "200": { "description": "Wallet tier status", "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet", "tier", "lease_started_at", "lease_expires_at", "active", "organization_lifecycle_state", "lease_perpetual", "lease", "lease_days", "downgraded_at", "pool_usage", "projects" ], "properties": { "wallet": { "type": "string", "description": "Lowercased wallet address." }, "tier": { "type": "string", "nullable": true, "enum": [ "prototype", "hobby", "team", null ], "description": "Current tier, or null if the wallet has never subscribed." }, "lease_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 timestamp when the current lease began. Null if no tier." }, "lease_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO-8601 timestamp when the current lease expires. Null if no tier." }, "active": { "type": "boolean", "description": "True when a tier is set and the lease is perpetual or its effective expiry is in the future. Perpetual effective expiry is null." }, "organization_lifecycle_state": { "type": "string", "nullable": true, "enum": [ "active", "past_due", "frozen", "dormant", "purged", null ], "description": "Lifecycle state of the owning organization. Null only for orphan wallets with no organization row." }, "lease_perpetual": { "type": "boolean", "nullable": true, "description": "Operator escape hatch flag on the owning organization. When true, the organization never advances past 'active' regardless of lease expiry. Null only for orphan wallets." }, "lease": { "type": "string", "nullable": true, "enum": [ "perpetual", "leased", null ], "description": "kygit-handoff D4 — 'perpetual' for a lease-less tier (prototype: one x402 payment, never expires, never scheduler-advanced), 'leased' for hobby/team. Null only when tier is null." }, "lease_days": { "type": "integer", "nullable": true, "description": "kygit-handoff D4 — days remaining on a LEASED tier (ceil, floored at 0), or null for a perpetual tier or no tier." }, "downgraded_at": { "type": "string", "format": "date-time", "nullable": true, "description": "kygit-handoff D4 — ISO-8601 timestamp of the organization's most recent lifecycle-ladder downgrade to perpetual prototype (the ladder's terminal transition; nothing is deleted, hobby/team capacity is restored on renewal). Null if the organization has never been downgraded." }, "pool_usage": { "type": "object", "required": [ "projects", "total_api_calls", "total_storage_bytes", "gitvault_source_bytes", "api_calls_limit", "storage_bytes_limit", "source_bytes_limit", "gitvault_egress_bytes_used", "gitvault_egress_bytes_limit" ], "description": "Aggregate usage across all active projects owned by this wallet, PLUS the organization's retained gitvault vault bytes.", "properties": { "projects": { "type": "integer", "description": "Number of active projects owned by the wallet." }, "total_api_calls": { "type": "integer", "description": "Sum of api_calls across the wallet's active projects." }, "total_storage_bytes": { "type": "integer", "description": "App storage: sum of storage_bytes across the wallet's active projects PLUS gitvault_source_bytes, folded together for a single at-a-glance figure. The tier limit it is compared against is storage_bytes_limit; gitvault's OWN limit is the separate source_bytes_limit below (kygit-handoff D4 — two pooled terms, two limits)." }, "gitvault_source_bytes": { "type": "integer", "description": "The gitvault half of total_storage_bytes, broken out — and the figure compared against source_bytes_limit. Counts EVERY vault in the organization, including vaults whose project has been deleted: vault ciphertext is retained permanently (V0 has no purge verb), so its bytes stay pooled." }, "api_calls_limit": { "type": "integer", "description": "Tier API-call cap. 0 when no tier is set." }, "storage_bytes_limit": { "type": "integer", "description": "Tier app-storage cap in bytes. 0 when no tier is set." }, "source_bytes_limit": { "type": "integer", "description": "kygit-handoff D4 — the org-pooled gitvault vault-bytes cap, a SEPARATE limit from storage_bytes_limit (prototype 1 GiB / hobby 10 GiB / team 50 GiB). A gitvault QUOTA_EXCEEDED refusal with details.resource:\"source_bytes\" is computed against gitvault_source_bytes vs this figure. 0 when no tier is set." }, "gitvault_egress_bytes_used": { "type": "integer", "description": "kygit-handoff D4 — bytes read from the org's vaults this calendar month (UTC), counted at read authorization by stored object size. Prototype-only allowance; always 0 on a leased tier (unmetered)." }, "gitvault_egress_bytes_limit": { "type": "integer", "nullable": true, "description": "kygit-handoff D4 — max(3 GiB, 3 x gitvault_source_bytes) on prototype; null on hobby/team (leased tiers are unmetered by this allowance in this change). Over it, object reads refuse 403 QUOTA_EXCEEDED with details.resource:\"gitvault_egress_bytes\"." } } }, "projects": { "type": "array", "description": "Non-terminal projects owned by the wallet, with lifecycle and pin state.", "items": { "$ref": "#/components/schemas/WalletTierProject" } }, "advisories": { "type": "array", "description": "recovery-event-reachability: org-level advisories. Present only when at least one applies. `operator_unreachable` means the owning organization resolves to zero verified notification recipients, so mandatory recovery/security notifications currently have no human to reach.", "items": { "type": "object", "required": [ "type", "summary", "next_actions" ], "properties": { "type": { "type": "string", "enum": [ "operator_unreachable" ] }, "summary": { "type": "string" }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "why": { "type": "string" } } } } } } }, "platform_status": { "type": "string", "enum": [ "degraded" ], "description": "Health-assessment rider. Present and equal to `degraded` only while an open platform incident is global or affects one of this caller's projects; omitted when clear. Read the project events feed (`platform_incident` entries + the `platform_incidents[]` overlay) for the incident detail. The same rider appears on GET /agent/v1/operator/status and the events-feed envelope, and nowhere else." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/projects/v1": { "get": { "tags": [ "Projects" ], "summary": "List projects", "operationId": "listProjects", "description": "List the caller's owned projects from the server inventory — each with name, site_url, custom domains, the owning org (org_id), and status. A non-admin caller sees every project owned by an org on which their principal holds an active membership; admin credentials see all. Soft-deleted (tombstone) projects are NEVER listed; archived projects are hidden by default and opt back in with `include=archived`. Supports cursor-based pagination. Filter to one org with `org_id` (authorize-before-reveal: a non-member or guessed id gets the same 403 as a real-but-unauthorized org). Auth: SIWX wallet (SIGN-IN-WITH-X header), a control-plane session bearer (the operator console's signed-in human — membership-scoped exactly like a SIWX-resolved principal), or admin credentials. Unauthenticated calls return 402 with `auth: \"SIWX\"`. For tier pricing, use GET /tiers/v1.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] }, { "adminKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Maximum number of projects to return (default 50, max 200)" }, { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "Cursor for pagination (from previous response's next_cursor)" }, { "name": "org_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Filter to projects owned by this org (organization). Authorize-before-reveal: a non-member or guessed id returns the same 403 as a real-but-unauthorized org." }, { "name": "include", "in": "query", "schema": { "type": "string", "enum": [ "archived" ] }, "description": "Opt archived projects back into the listing (`include=archived`). Soft-deleted (tombstone) projects are never returned regardless. Any other value is a 400." } ], "responses": { "200": { "description": "Project list", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "required": [ "project_id", "name", "tier", "status", "org_id", "created_at", "pinned" ], "properties": { "name": { "type": "string" }, "tier": { "type": "string", "enum": [ "prototype", "hobby", "team" ] }, "status": { "type": "string" }, "org_id": { "type": "string", "format": "uuid", "nullable": true, "description": "The owning org (organization). A wallet never owns a project; authority is org membership or a project grant." }, "created_by": { "type": "string", "format": "uuid", "nullable": true, "description": "v1.77: the control-plane principal that provisioned the project (provenance, not authorization)." }, "creator": { "allOf": [ { "$ref": "#/components/schemas/OperationActorSnapshot" } ], "nullable": true, "description": "Immutable creation-time actor snapshot. Null for unresolved legacy rows; never live-enriched after linking, rename, revoke, or transfer." }, "created_at": { "type": "string", "format": "date-time" }, "site_url": { "type": "string", "nullable": true, "description": "Primary public URL: the first claimed run402.com subdomain, else the first custom domain, else null." }, "custom_domains": { "type": "array", "items": { "type": "string" }, "description": "Every custom hostname mapped to this project (empty when none). The run402.com subdomain is not a custom domain." }, "pinned": { "type": "boolean" }, "project_id": { "$ref": "#/components/schemas/ProjectId" } } } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Projects" ], "summary": "Provision a new project", "operationId": "createProject", "description": "Creates a new database project. Requires wallet auth (EIP-4361 signature). Free within your active tier. The wallet must have an active tier subscription.", "security": [ { "walletAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional project name" }, "org_id": { "type": "string", "format": "uuid", "description": "Optional owning org. Caller must hold developer+ membership. Omit for the wallet's own org." } } } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectCreated" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/projects/v1/quote": { "post": { "tags": [ "Projects" ], "summary": "Get tier pricing quote", "operationId": "quoteProjectPricing", "description": "Returns tier pricing (price, lease_days, storage_mb, api_calls per tier). Free, no auth. Backwards-compatible alias for clients pinned to this path; the canonical pricing endpoint is GET /tiers/v1.", "responses": { "200": { "description": "Tier pricing quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "tiers": { "type": "object", "additionalProperties": { "type": "object", "properties": { "price": { "type": "string", "description": "USD price string (e.g. \"0.10\")" }, "lease_days": { "type": "integer", "nullable": true, "description": "null for a perpetual tier (kygit-handoff D4 — prototype)." }, "storage_mb": { "type": "integer" }, "api_calls": { "type": "integer" } }, "required": [ "price", "lease_days", "storage_mb", "api_calls" ] } } }, "required": [ "tiers" ] } } } } } } }, "/projects/v1/{project_id}": { "get": { "tags": [ "Projects" ], "summary": "Read a single project (authoritative)", "operationId": "getProject", "description": "Returns the authoritative server-side view of one project: identity, owning org, tier, lifecycle, public addressing (site_url + custom domains), last deploy, mailbox address(es), and usage versus tier limits. Authorized via the project.read action - a control-plane principal (SIWx wallet or session) with at least viewer access to the owning org, or platform admin. Authorize-before-reveal: a non-authorized caller (including a guessed id) gets the same 403, never a 404 that confirms existence. No secret or key value is ever returned.", "security": [ { "controlPlaneSession": [] }, { "walletAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } } ], "responses": { "200": { "description": "The authoritative project view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "$ref": "#/components/schemas/ProjectId" }, "public_id": { "type": "string", "example": "abc123" }, "name": { "type": "string", "nullable": true }, "org_id": { "type": "string" }, "tier": { "type": "string", "example": "team" }, "effective_status": { "type": "string", "example": "active" }, "organization_lifecycle_state": { "type": "string", "example": "active" }, "site_url": { "type": "string", "nullable": true, "example": "https://my-app.run402.com" }, "custom_domains": { "type": "array", "items": { "type": "string" } }, "last_deploy": { "type": "object", "nullable": true, "properties": { "release_id": { "type": "string" }, "activated_at": { "type": "string", "format": "date-time" } } }, "mailbox": { "type": "array", "items": { "type": "string" } }, "usage": { "type": "object", "properties": { "api_calls": { "type": "integer" }, "storage_bytes": { "type": "integer" }, "api_calls_limit": { "type": "integer" }, "storage_bytes_limit": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "nullable": true, "description": "Legacy creating-principal field retained unchanged." }, "creator": { "allOf": [ { "$ref": "#/components/schemas/OperationActorSnapshot" } ], "nullable": true, "description": "Immutable action-time creator snapshot. The org_id remains the project owner." } } } } } }, "403": { "description": "Not authorized for this project (authorize-before-reveal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Projects" ], "summary": "Archive (soft-delete) a project", "operationId": "deleteProject", "description": "Archives and soft-deletes a project. Compatibility path accepts service_key or admin auth. Control-plane session / SIWX callers must satisfy the owner-only project.delete policy; browser sessions require passkey step-up, while SIWX wallet signatures are fresh per request.", "security": [ { "controlPlaneSession": [] }, { "walletAuth": [] }, { "serviceKey": [] }, { "adminKey": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } } ], "responses": { "200": { "description": "Project purged (terminal delete). When the project had a gitvault vault, the response additionally discloses that the vault SURVIVES the delete.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "purged" }, "project_id": { "$ref": "#/components/schemas/ProjectId" }, "gitvault": { "type": "object", "description": "Present ONLY when the deleted project had a gitvault vault. Deleting a project does NOT delete its vault: the encrypted history still restores via `git fetch run402::/ refs/run402/deploys/latest`, its bytes still count against the organization's pooled storage, and no client command removes it (V0 has no purge verb, and `prune` requires an owner-signed intent plus two verifier receipts). Absent for projects with no vault, whose response is unchanged.", "properties": { "repo_id": { "type": "string", "example": "src_871e832894fa5eb7ce402fbe1c214397" }, "retained": { "type": "boolean", "example": true }, "source_bytes": { "type": "string", "description": "Retained vault bytes, still pooled against the organization's storage limit (see pool_usage.gitvault_source_bytes on GET /tiers/v1/status).", "example": "1058300" }, "counts_against_org_storage": { "type": "boolean", "example": true }, "removable_by_client": { "type": "boolean", "description": "Always false in V0 — no client-invocable purge exists for a retained vault.", "example": false } } }, "warnings": { "type": "array", "description": "Present only alongside `gitvault`: a single `gitvault_vault_retained` entry stating what survived the delete.", "items": { "type": "object", "properties": { "kind": { "type": "string", "example": "gitvault_vault_retained" }, "message": { "type": "string" } } } }, "next_actions": { "type": "array", "description": "Present only alongside `gitvault`: `inspect_vault` (the retained vault's record) and `check_usage` (its bytes in pooled storage).", "items": { "$ref": "#/components/schemas/NextAction" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "Projects" ], "summary": "Rename a project", "operationId": "renameProject", "description": "Updates the project's display name. Authorize-before-reveal: requires an admin-or-above membership on the owning org (or a project:write grant). A non-authorized caller (including a guessed id) gets the same 403 as a real-but-unauthorized project, never a 404 that confirms existence.", "security": [ { "controlPlaneSession": [] }, { "walletAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 200, "example": "My Site" } } } } } }, "responses": { "200": { "description": "Project renamed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "$ref": "#/components/schemas/ProjectId" }, "name": { "type": "string" } } } } } }, "400": { "description": "Invalid name (empty, too long, or control characters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized for this project action (authorize-before-reveal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/projects/v1/{project_id}/repo-name": { "post": { "tags": [ "Projects" ], "summary": "Claim or rename the project's address-form repo name (repo-first-onramp D6)", "operationId": "claimRepoName", "description": "Explicit claim/rename of the project's per-org-unique, address-form name (`run402::/`) — the address counterpart to the free-text display `name` on PATCH /projects/v1/{project_id}, which is left untouched. A project also acquires this name implicitly via push-to-create (POST /gitvault/v1/vaults with {org_slug, repo_name}); this route is the explicit alternative. No fee. Same authority tier as renaming the display name (project.rename).", "security": [ { "controlPlaneSession": [] }, { "walletAuth": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Lowercase [a-z0-9-], no leading/trailing/double hyphen, at most 63 characters." } } } } } }, "responses": { "200": { "description": "The project's repo name, claimed or renamed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "$ref": "#/components/schemas/ProjectId" }, "repo_name": { "type": "string" }, "previous_repo_name": { "type": [ "string", "null" ], "description": "The project's prior address-form name, or null if this is its first claim." } } } } } }, "400": { "description": "Invalid name (grammar violation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not authorized for this project action (authorize-before-reveal).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Name already claimed by another project in this org (REPO_NAME_TAKEN).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/projects/v1/{project_id}/transfers": { "post": { "tags": [ "Project Transfers" ], "summary": "Initiate a project transfer (to a wallet, email, or owned org)", "operationId": "initiateProjectTransfer", "description": "Transfer a project to another owner. Address the recipient by EXACTLY ONE of to_wallet (a two-party SIWX handoff completed via /accept), to_email (an email handoff claimed via /claim), or to_org_id (same-actor move into another org the caller already owns, completed synchronously). Supplying multiple recipient fields, or none, returns 400 VALIDATION_FAILED. Email-addressed transfers may include retain_collaborator: { role: \"developer\" }; wallet/org-addressed transfers reject it. kysigned_record_id is wallet-only. Either pending party can cancel wallet/email transfers; otherwise they auto-expire at 72h. Single-pending-per-project (partial UNIQUE index) → 409 PENDING_TRANSFER_EXISTS. Auth: SIWX wallet, or a control-plane session (step-up gated). Org-addressed same-actor moves require active owner membership on both source and destination orgs; non-same-actor org transfers are reserved for a future interactive flow and currently return 403 FORBIDDEN.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ProjectId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide exactly one of to_wallet, to_email, or to_org_id.", "properties": { "to_wallet": { "type": "string", "description": "Recipient wallet address (canonical-lowercase). Mutually exclusive with to_email and to_org_id; must differ from the initiator. Completed via POST /agent/v1/transfers/{transfer_id}/accept." }, "to_email": { "type": "string", "format": "email", "description": "Recipient email address. Mutually exclusive with to_wallet and to_org_id. The recipient claims via POST /agent/v1/transfers/{transfer_id}/claim, choosing an org they own or creating a new one." }, "to_org_id": { "type": "string", "format": "uuid", "description": "Destination org id for a same-actor move. Mutually exclusive with to_wallet and to_email. In this version, the caller must be an active owner of both the source org and destination org; the move completes synchronously with a 200 response." }, "billing_policy": { "type": "string", "enum": [ "migrate" ], "default": "migrate", "description": "Phase 1A only supports 'migrate' (single billing-migration mutation). 'inherit' returns 400 INVALID_BILLING_POLICY." }, "message": { "type": "string", "description": "Optional human-readable note carried in notification emails to both parties." }, "retain_collaborator": { "type": "object", "description": "Email-addressed transfers only. Optional sender proposal to stay on as a developer of the recipient org after claim; materialized only when the recipient passes accept_retained_collaborator: true.", "properties": { "role": { "type": "string", "enum": [ "developer" ] } }, "required": [ "role" ] }, "kysigned_record_id": { "type": "string", "description": "Wallet-addressed transfers only. Optional KySigned attestation record id. Recorded as-is in Phase 1A; verification ships in Phase 1B." } } } } } }, "responses": { "200": { "description": "Same-actor org transfer completed synchronously. Returned only for to_org_id when the caller owns both orgs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string" }, "from_organization_id": { "type": "string", "format": "uuid" }, "to_organization_id": { "type": "string", "format": "uuid" }, "completed_at": { "type": "string", "format": "date-time" }, "secrets_rotation_advised": { "type": "boolean", "enum": [ true ] }, "secret_names_inherited": { "type": "array", "items": { "type": "string" }, "description": "Names of every secret currently on the project. Values transfer with the project but are never returned." }, "secrets_count_inherited": { "type": "integer" }, "github_repo_note": { "type": "string" }, "ci_bindings_suspended": { "type": "integer", "description": "Count of CI/OIDC (ci_oidc) bindings revoked by this move. When > 0, push-to-deploy is suspended until re-linked (run402 ci link github)." }, "ci_bindings_note": { "type": "string", "description": "Present only when ci_bindings_suspended > 0: explains the CI/OIDC revocation and how to re-link." }, "next_actions": { "type": "array", "description": "Present only when ci_bindings_suspended > 0: a single re-link-CI action.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "method": { "type": "string" }, "path": { "type": "string" }, "auth": { "type": "string" }, "why": { "type": "string" } } } }, "anon_key": { "type": "string", "description": "JWT for client-side access to the moved project (apikey header)." }, "service_key": { "type": "string", "description": "JWT for admin access to the moved project (Authorization: Bearer)." } } } } } }, "201": { "description": "Pending wallet or email transfer created", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "project_summary": { "type": "object", "properties": { "project_id": { "type": "string" }, "project_name": { "type": "string", "nullable": true }, "billing_policy": { "type": "string", "enum": [ "migrate" ] }, "from_wallet": { "type": "string" }, "to_wallet": { "type": "string" } } }, "your_unused_lease_days": { "type": "integer", "minimum": 0 }, "lease_refundable": { "type": "boolean", "enum": [ false ] }, "terms_sha256": { "type": "string", "description": "Canonical-hash over {project_id, from_wallet, to_wallet, billing_policy, expires_at}. Phase 1B's KySigned verifier compares this to the record's terms hash." } } } } } }, "400": { "description": "VALIDATION_FAILED, INVALID_RECIPIENT, or INVALID_BILLING_POLICY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "FORBIDDEN — caller is not authorized for the source project or, for to_org_id, lacks active owner membership on the destination org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "PENDING_TRANSFER_EXISTS, ALREADY_OWNED, RECIPIENT_ORGANIZATION_NOT_ACTIVE, or PROJECT_NOT_TRANSFERABLE", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/transfers/incoming": { "get": { "tags": [ "Project Transfers" ], "summary": "List pending transfers offered TO the caller", "operationId": "listIncomingTransfers", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Array of pending transfer summaries; each entry carries a preview_path the SDK / CLI / UI can deep-link to.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTransferSummary" } } } } } } } } } }, "/agent/v1/transfers/outgoing": { "get": { "tags": [ "Project Transfers" ], "summary": "List pending transfers initiated BY the caller", "operationId": "listOutgoingTransfers", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Same shape as the incoming endpoint, filtered to transfers where the caller is from_wallet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfers": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTransferSummary" } } } } } } } } } }, "/agent/v1/transfers/{transfer_id}": { "get": { "tags": [ "Project Transfers" ], "summary": "Safe review preview document for a pending transfer", "operationId": "previewProjectTransfer", "description": "Kind-agnostic preview. Wallet-addressed transfers are visible to from_wallet or to_wallet; email-addressed transfers are visible to the addressed-email principal or offering-org members. Returns the full transfer footprint, including payment_drain with its cutoff generation, blockers, active leases, and outgoing-generation settled-intent count. Secret NAMES are returned; values never are. Third-party viewers receive 403; non-existent transfer ids receive 404.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Preview document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectTransferPreview" } } } }, "403": { "description": "FORBIDDEN — signer is not party to this transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "TRANSFER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/transfers/{transfer_id}/accept": { "post": { "tags": [ "Project Transfers" ], "summary": "Accept a pending project transfer (recipient B signs)", "operationId": "acceptProjectTransfer", "description": "Atomic transaction: wallet flip + CI binding revoke + notification enqueue (one per recipient) + secrets-rotation advisory stamp + audit row, all in one COMMIT. Routes scope by transfer_id (NOT project_id) — stale-offer safe. Five distinct pre-condition codes: OPERATOR_EMAIL_NOT_VERIFIED (412), RECIPIENT_ORGANIZATION_NOT_ACTIVE (409), PROJECT_NOT_TRANSFERABLE (409), PROJECT_OWNER_CHANGED (409), TRANSFER_EXPIRED (410). Uses clock_timestamp() for the expiry check (NOT NOW() — would be stale under lock waits).", "security": [ { "walletAuth": [] } ], "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Accept succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptTransferResponse" } } } }, "403": { "description": "FORBIDDEN — signer is not the to_wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "TRANSFER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "TRANSFER_ALREADY_PROCESSED / RECIPIENT_ORGANIZATION_NOT_ACTIVE / PROJECT_NOT_TRANSFERABLE / PROJECT_OWNER_CHANGED / PAYMENT_DESTINATION_DRAINING / PAYMENT_DESTINATION_CHANGED / WRONG_COMPLETION_FOR_TRANSFER_KIND. A draining response carries Retry-After and must be repeated with the same transfer id; it never advances the ownership epoch early.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "TRANSFER_EXPIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "OPERATOR_EMAIL_NOT_VERIFIED — B must verify their operator email first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/agent/v1/transfers/{transfer_id}/claim": { "post": { "tags": [ "Project Transfers" ], "summary": "Complete an email-addressed transfer (claim into an org)", "operationId": "claimProjectTransfer", "description": "The EMAIL completion ceremony. The addressed-email principal claims the transfer into an org they own (org_id) or omits it to create a new wallet-less org. Atomically repoints project ownership and re-homes authority — the same engine as the wallet /accept. If the preview carries retain_collaborator, accept_retained_collaborator: true keeps the sender on as a developer; default false severs access. Calling claim on a wallet-addressed row returns 409 WRONG_COMPLETION_FOR_TRANSFER_KIND pointing at /accept on the same transfer id.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/SiwxHeader" }, { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "org_id": { "type": "string", "format": "uuid", "description": "An org the claimer owns to receive the project; omit to create a new wallet-less org." }, "accept_retained_collaborator": { "type": "boolean", "description": "Opt-in. When the preview carries retain_collaborator, true keeps the sender on as a developer of the receiving org; default false severs access." } } } } } }, "responses": { "200": { "description": "Claimed (ownership flipped; status: accepted)", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "WRONG_COMPLETION_FOR_TRANSFER_KIND (wallet-addressed row — use /accept) / TRANSFER_ALREADY_PROCESSED", "content": { "application/json": { "schema": { "type": "object" } } } }, "412": { "description": "Addressed email not verified (OPERATOR_EMAIL_NOT_VERIFIED)", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/agent/v1/transfers/{transfer_id}/cancel": { "post": { "tags": [ "Project Transfers" ], "summary": "Cancel a pending project transfer", "operationId": "cancelProjectTransfer", "description": "Kind-agnostic cancel. Wallet-addressed transfers may be cancelled by either signing party; email-addressed transfers may be cancelled by offering-org owner/admin. Body accepts an optional reason string. Returns 403 for unauthorized callers; 409 if the row is already terminal.", "security": [ { "walletAuth": [] }, { "controlPlaneSession": [] } ], "parameters": [ { "name": "transfer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional cancellation reason; surfaced in notification emails to both parties." } } } } } }, "responses": { "200": { "description": "Transfer cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "transfer_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "cancelled" ] }, "cancelled_by": { "type": "string", "enum": [ "from_wallet", "to_wallet", "system" ] }, "cancellation_reason": { "type": "string", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time" } } } } } }, "403": { "description": "FORBIDDEN — signer not party to transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "TRANSFER_NOT_FOUND", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "TRANSFER_ALREADY_PROCESSED (the unified cancel routes by kind; an email-addressed row is cancelled by the offering-org owner/admin)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/auth/v1/signup": { "post": { "tags": [ "Auth" ], "summary": "Create a new user", "operationId": "signup", "security": [ { "apikey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 6 }, "is_admin": { "type": "boolean", "description": "Only honored when the request uses the project's service key." } } } } } }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "created_at": { "type": "string", "format": "date-time" }, "is_admin": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Public signup disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "User already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Creates a password user. Public signup is accepted only when project public_signup is open; service keys may create users regardless and can set is_admin=true." } }, "/auth/v1/magic-link": { "post": { "tags": [ "Auth" ], "summary": "Request passwordless email authentication", "description": "Requests link, code, or both delivery for sign-in, invite, claim, or recovery. delivery defaults to link. redirect_url is required for link/both and optional for code. A syntactically valid anonymous request receives generic accepted wording regardless of account existence; acceptance does not claim provider delivery. code/both returns only an opaque challenge_id, never the code. intent=invite requires a service key and produces trusted state.", "security": [ { "apikey": [] }, { "apikey": [], "serviceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "redirect_url": { "type": "string", "format": "uri", "description": "URL to redirect to with ?token=. Must be an allowed origin for this project and must be served by a document that exchanges the token. If the active release serves this path through a GET static route alias, the 200 response includes a MAGIC_LINK_REDIRECT_STATIC_ALIAS warning." }, "delivery": { "type": "string", "enum": [ "link", "code", "both" ], "default": "link", "description": "Credential(s) included in the email. redirect_url is required for link/both." }, "intent": { "type": "string", "enum": [ "signin", "invite", "claim", "recovery" ], "default": "signin" }, "client_state": { "description": "Opaque app state, preserved through magic-link exchange. Strings are stored as-is; other JSON values are stringified. Maximum 2048 UTF-8 bytes.", "nullable": true } } } } } }, "responses": { "200": { "description": "Request accepted. code/both may include an opaque challenge_id; warnings are preserved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthMagicLinkResponse" } } } }, "400": { "description": "Invalid delivery/input, missing redirect_url for link/both, or redirect_url not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Service key required for invite intent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited (per-email or per-project)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "operationId": "requestMagicLink" } }, "/auth/v1/admin/users": { "post": { "tags": [ "Auth" ], "summary": "Create or update an auth user", "description": "Service-key endpoint for creating a project auth user, changing admin status, and optionally sending a trusted invite magic link. Lifecycle-gated for non-active projects and DB-rate-limited by project, email, and service-key identity.", "operationId": "adminCreateAuthUser", "security": [ { "apikey": [] }, { "apikey": [], "serviceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "is_admin": { "type": "boolean" }, "send_invite": { "type": "boolean", "default": false }, "redirect_url": { "type": "string", "format": "uri", "description": "Required when send_invite=true. Must be an allowed project auth redirect origin." }, "client_state": { "description": "Optional opaque state included in the trusted invite token.", "nullable": true } } } } } }, "responses": { "200": { "description": "Existing user updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "is_admin": { "type": "boolean" }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created": { "type": "boolean" }, "invite_sent": { "type": "boolean" } } } } } }, "201": { "description": "User created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "is_admin": { "type": "boolean" }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "created": { "type": "boolean", "enum": [ true ] }, "invite_sent": { "type": "boolean" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Service key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/passkeys/register/options": { "post": { "tags": [ "Auth" ], "summary": "Create passkey registration options", "description": "Creates a WebAuthn registration challenge for the authenticated user at the supplied app_origin.", "operationId": "createPasskeyRegistrationOptions", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_origin" ], "properties": { "app_origin": { "type": "string", "format": "uri", "description": "Exact allowed app origin for the WebAuthn ceremony." } } } } } }, "responses": { "200": { "description": "Registration options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptionsResponse" } } } }, "400": { "description": "Invalid app_origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Recent passkey auth required for admin passkey mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/passkeys/register/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify passkey registration", "description": "Verifies a WebAuthn registration response and stores the caller's passkey.", "operationId": "verifyPasskeyRegistration", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "response" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "response": { "type": "object", "description": "PublicKeyCredential JSON from the browser.", "additionalProperties": true }, "label": { "type": "string", "nullable": true } } } } } }, "responses": { "201": { "description": "Passkey registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Recent passkey auth required for admin passkey mutation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/passkeys/login/options": { "post": { "tags": [ "Auth" ], "summary": "Create passkey login options", "description": "Creates a WebAuthn login challenge. Optional email hints are accepted, but options remain discoverable and do not expose allowCredentials.", "operationId": "createPasskeyLoginOptions", "security": [ { "apikey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "app_origin" ], "properties": { "app_origin": { "type": "string", "format": "uri", "description": "Exact allowed app origin for the WebAuthn ceremony." }, "email": { "type": "string", "format": "email" } } } } } }, "responses": { "200": { "description": "Login options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptionsResponse" } } } }, "400": { "description": "Invalid app_origin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/passkeys/login/verify": { "post": { "tags": [ "Auth" ], "summary": "Verify passkey login", "description": "Verifies a WebAuthn assertion and returns a normal auth session. Rate-limited by project, RP ID, IP, and invalid challenge attempts before challenge consumption. The JWT includes amr=[passkey], aal=aal2, auth_time, and passkey_id.", "operationId": "verifyPasskeyLogin", "security": [ { "apikey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "challenge_id", "response" ], "properties": { "challenge_id": { "type": "string", "format": "uuid" }, "response": { "type": "object", "description": "PublicKeyCredential JSON from the browser.", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Session issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/passkeys": { "get": { "tags": [ "Auth" ], "summary": "List passkeys", "description": "Lists the caller's active passkeys for the current project.", "operationId": "listPasskeys", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Passkey list", "content": { "application/json": { "schema": { "type": "object", "required": [ "passkeys" ], "properties": { "passkeys": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyRecord" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/passkeys/{passkey_id}": { "delete": { "tags": [ "Auth" ], "summary": "Delete a passkey", "description": "Soft-deletes one caller-owned passkey. Required-passkey admins need recent passkey auth and cannot delete their last eligible admin passkey.", "operationId": "deletePasskey", "security": [ { "apikey": [], "bearerAuth": [] } ], "parameters": [ { "name": "passkey_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Recent passkey auth required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Passkey not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Cannot delete the last eligible admin passkey", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/v1/user/password": { "post": { "tags": [ "Auth" ], "summary": "Change, reset, or set password", "description": "Three modes: (1) Change: provide current_password + new_password. (2) Reset via magic link: login with magic link, call with just new_password. (3) Set for passwordless user: requires project allow_password_set=true. Requires BOTH the project apikey header AND the user access_token as Authorization: Bearer.", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_password" ], "properties": { "current_password": { "type": "string", "description": "Required for password change (not for reset/set)" }, "new_password": { "type": "string" } } } } } }, "responses": { "200": { "description": "Password updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusOk" } } } }, "401": { "description": "Wrong current_password or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Password set not enabled for this project (passwordless user)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "operationId": "setUserPassword" } }, "/auth/v1/settings": { "patch": { "tags": [ "Auth" ], "summary": "Update project auth settings", "description": "Updates project auth settings. Requires the project's service key, passed either as apikey or as Authorization: Bearer with the anon apikey. Lifecycle-gated for non-active projects.", "security": [ { "apikey": [] }, { "apikey": [], "serviceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_password_set": { "type": "boolean", "description": "Allow passwordless users to set a password (default: false)" }, "preferred_sign_in_method": { "type": "string", "nullable": true, "enum": [ "password", "magic_link", "oauth_google", "passkey", null ] }, "public_signup": { "type": "string", "enum": [ "open", "known_email", "invite_only" ] }, "require_passkey_for_project_admin": { "type": "boolean" }, "test_mode": { "type": "boolean", "nullable": true, "description": "Tri-state auth test-session mode. true enables service-key test sessions, false disables them, null restores the tier default (prototype on, paid tiers off)." } } } } } }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSettingsResponse" } } } }, "400": { "description": "Invalid settings request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Service key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Security-sensitive settings are not enabled for this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "operationId": "updateAuthSettings" } }, "/auth/v1/token": { "post": { "tags": [ "Auth" ], "summary": "Login or refresh token", "operationId": "getToken", "security": [ { "apikey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } }, "title": "Password login" }, { "type": "object", "required": [ "refresh_token", "grant_type" ], "properties": { "refresh_token": { "type": "string" }, "grant_type": { "type": "string", "enum": [ "refresh_token" ] } }, "title": "Token refresh" }, { "type": "object", "required": [ "grant_type", "token" ], "properties": { "grant_type": { "type": "string", "enum": [ "magic_link" ] }, "token": { "type": "string", "description": "Single-use token delivered to the user's email inbox via POST /auth/v1/magic-link." } }, "title": "Magic link login" }, { "type": "object", "required": [ "grant_type", "challenge_id", "code" ], "properties": { "grant_type": { "type": "string", "enum": [ "email_code" ] }, "challenge_id": { "type": "string", "format": "uuid", "description": "Opaque handle returned by a code/both request; not a credential." }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "Secret six-digit credential delivered by email." } }, "title": "Email code login" } ] } } } }, "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSessionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/v1/user": { "get": { "tags": [ "Auth" ], "summary": "Get current user", "description": "Returns the current user's profile, linked identities, and passkey state. Optional app_origin query parameter validates the current RP and returns has_passkey_for_current_rp.", "operationId": "getUser", "security": [ { "apikey": [], "bearerAuth": [] } ], "responses": { "200": { "description": "Current user info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUserResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "name": "app_origin", "in": "query", "required": false, "schema": { "type": "string", "format": "uri" }, "description": "Exact app origin to evaluate for current-rp passkey state." } ] } }, "/auth/v1/logout": { "post": { "tags": [ "Auth" ], "summary": "Logout / invalidate refresh token", "description": "Invalidates the refresh_token. Requires BOTH the project apikey header AND the user access_token as Authorization: Bearer.", "operationId": "logout", "security": [ { "apikey": [], "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Logged out", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" } } } } } } } } }, "/auth/v1/sessions/end": { "post": { "tags": [ "Auth" ], "summary": "End the browser session (programmatic sign-out)", "description": "Programmatic sign-out targeted by the @run402/functions auth.sessions.endResponse() helper. Served on the tenant host. NOT behind apikey and NOT CSRF-gated: the session cookie is SameSite=Lax, so a cross-site POST never carries it. Best-effort revokes the session carried in the __Host-Http-r402_session cookie when present, and always returns a clear-cookie Set-Cookie. Idempotent — a missing/invalid cookie still returns ok with no session-existence oracle.", "operationId": "sessionsEnd", "security": [], "responses": { "200": { "description": "Signed out; the session cookie is cleared.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true } } } } } } } } }, "/auth/v1/providers": { "get": { "tags": [ "Auth" ], "summary": "List available auth providers", "operationId": "getAuthProviders", "description": "Returns available authentication providers plus passkey, project auth setting hints, and magic_link.delivery_modes. Clients treat an absent delivery_modes field as link-only compatibility.", "security": [ { "apikey": [] } ], "responses": { "200": { "description": "Provider list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthProvidersResponse" } } } } } } }, "/auth/v1/test-sessions": { "post": { "tags": [ "Auth" ], "summary": "Mint a deterministic tenant test session", "operationId": "createAuthTestSession", "description": "Service-key-only helper for tests and CI. Creates or reuses a watermarked `.test.invalid` tenant user derived from `label`, returns a 2-hour browser-session cookie value and a 2-hour bearer access token, and marks actor context with `isTest`.", "security": [ { "apikey": [], "serviceKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,31}$", "description": "Deterministic local label. The email becomes