{
  "openapi": "3.1.0",
  "info": {
    "title": "SOLE Mega Gate API",
    "version": "2026-06-08.sdk-contract",
    "summary": "Shared FS27 identity, PIN, recovery, owner session, and SkyePay handoff contract for Sol surfaces.",
    "description": "The SOLE Mega Gate keeps visual access on Sol while FS27 issues sessions and SkyePay handles commerce. Public clients use shared gate bearer headers; this contract does not define a separate Sol password system."
  },
  "servers": [
    {
      "url": "https://skyegatefs27-citadeldb.graylondonskyes.workers.dev",
      "description": "FS27 runtime authority"
    },
    {
      "url": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public",
      "description": "SkyeNet shared-origin Sol package"
    }
  ],
  "security": [
    {
      "sharedGateBearer": []
    }
  ],
  "x-sole-megagate": {
    "browser_global": "SoleMegaGateClient",
    "browser_sdk": "https://solenterprises.org/assets/sole-megagate-client.js",
    "quickstart": "https://solenterprises.org/sdk/quickstart.json",
    "type_definitions": "https://solenterprises.org/sdk/sole-megagate-client.d.ts",
    "skynet_browser_sdk": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/assets/sole-megagate-client.js",
    "skynet_quickstart": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/sdk/quickstart.json",
    "skynet_type_definitions": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/sdk/sole-megagate-client.d.ts",
    "discovery_manifest": "https://solenterprises.org/.well-known/sole-megagate.json",
    "login_surface_manifest": "https://solenterprises.org/.well-known/sole-login-surfaces.json",
    "skynet_login_surface_manifest": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/.well-known/sole-login-surfaces.json",
    "sol_fs27_authority": "https://solenterprises.org/fs27/",
    "sol_fs27_role_host": "https://fs27.solenterprises.org/fs27/",
    "skynet_proof_surfaces": {
      "home": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/",
      "gate": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/gate/",
      "access_atlas": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/access/",
      "fs27_authority": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/fs27/",
      "mega_gate": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/login/",
      "bridge": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/bridge/",
      "pay": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/pay/",
      "store": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/store/",
      "sdk": "https://skyenet.graylondonskyes.workers.dev/solenterprises-public/sdk/"
    },
    "session_issuer": "FS27",
    "visual_system": "Bridge Estifarr",
    "local_app_passwords_allowed": false,
    "drop_in_form_selectors": [
      "data-sole-login-form",
      "data-sole-signup-form",
      "data-sole-pin-form",
      "data-sole-recovery-form",
      "data-sole-reset-form",
      "data-sole-owner-form",
      "data-sole-checkout-form",
      "data-sol-artist-support-panel",
      "data-sol-sovereign-auth-proof",
      "data-sole-session-status",
      "data-sole-form-status",
      "data-sole-logout"
    ],
    "commerce_intents": [
      "donate",
      "artist_store_support",
      "video_premiere_access",
      "artist_media_subscription",
      "release_support_credit"
    ],
    "browser_events": [
      "sole-megagate:forms-bound",
      "sole-megagate:session-status",
      "sole-megagate:request-success",
      "sole-megagate:request-error",
      "sole-megagate:login",
      "sole-megagate:signup",
      "sole-megagate:pin-login",
      "sole-megagate:recovery-login",
      "sole-megagate:forgot-password",
      "sole-megagate:owner-login",
      "sole-megagate:checkout",
      "sole-megagate:logout"
    ]
  },
  "components": {
    "securitySchemes": {
      "sharedGateBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Shared FS27/SkyGate/Free99/0S bearer token."
      },
      "xSkyeGateSession": {
        "type": "apiKey",
        "in": "header",
        "name": "x-skye-gate-session"
      },
      "xFree99GateSession": {
        "type": "apiKey",
        "in": "header",
        "name": "x-free99-gate-session"
      },
      "xZeroOsGateSession": {
        "type": "apiKey",
        "in": "header",
        "name": "x-0s-gate-session"
      }
    },
    "schemas": {
      "OkResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" }
        },
        "required": ["ok"]
      },
      "AuthPayload": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "format": "password" }
        }
      },
      "PinPayload": {
        "type": "object",
        "properties": {
          "gate_id": { "type": "string" },
          "pin": { "type": "string" },
          "credential": { "type": "string" }
        }
      },
      "RecoveryPayload": {
        "type": "object",
        "properties": {
          "gate_id": { "type": "string" },
          "recovery_code": { "type": "string" },
          "email": { "type": "string", "format": "email" }
        }
      },
      "CheckoutPayload": {
        "type": "object",
        "properties": {
          "client_slug": { "type": "string", "default": "metraiyux-0s" },
          "offer_id": { "type": "string" },
          "quantity": { "type": "integer", "minimum": 1 },
          "source": { "type": "string", "examples": ["solenterprises_storefront", "skyemusicnexus_artist_store"] },
          "skyemusicnexus_dynamic": { "type": "boolean", "description": "Enables dynamic SkyeMusicNexus artist-store checkout metadata." },
          "amount_cents": { "type": "integer", "minimum": 1 },
          "support_amount_cents": { "type": "integer", "minimum": 1 },
          "platform_fee_cents": { "type": "integer", "minimum": 0 },
          "support_goal_cents": { "type": "integer", "minimum": 0 },
          "support_prior_cents": { "type": "integer", "minimum": 0 },
          "support_balance_after_cents": { "type": "integer", "minimum": 0 },
          "support_credit_mode": { "type": "string", "examples": ["single_support_payment", "cumulative_artist_store_credit"] },
          "payment_kind": { "type": "string", "examples": ["artist_store_support", "video_premiere_access", "artist_media_subscription", "release_layaway"] },
          "fee_mode": { "type": "string", "examples": ["buyer_covered"] },
          "support_target_type": { "type": "string", "examples": ["artist", "video", "song", "album", "media_subscription"] },
          "support_target_url": { "type": "string" },
          "artist_name": { "type": "string" },
          "artist_slug": { "type": "string" },
          "product_id": { "type": "string" },
          "product_title": { "type": "string" },
          "product_type": { "type": "string" },
          "name_your_price": { "type": "boolean" },
          "support_no_max": { "type": "boolean" },
          "skyemusicnexus": {
            "type": "object",
            "description": "Artist-store metadata mirrored into SkyePay and Citadel order metadata for support, video, subscription, and release-credit flows."
          },
          "success_url": { "type": "string" },
          "cancel_url": { "type": "string" }
        }
      }
    }
  },
  "paths": {
    "/mega-gate/manifest": {
      "get": {
        "operationId": "megaGateManifest",
        "summary": "Read the live FS27 Mega Gate manifest.",
        "security": [],
        "responses": {
          "200": { "description": "Mega Gate manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkResponse" } } } }
        }
      }
    },
    "/auth/signup": {
      "post": {
        "operationId": "signup",
        "summary": "Create an FS27 account session where signup is enabled.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPayload" } } } },
        "responses": { "200": { "description": "Signup result" } }
      }
    },
    "/auth/login": {
      "post": {
        "operationId": "login",
        "summary": "Issue a shared FS27 gate session.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthPayload" } } } },
        "responses": { "200": { "description": "Login result" } }
      }
    },
    "/auth/pin/login": {
      "post": {
        "operationId": "pinLogin",
        "summary": "Issue a shared FS27 session from Gate ID and PIN.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinPayload" } } } },
        "responses": { "200": { "description": "PIN login result" } }
      }
    },
    "/auth/recovery/login": {
      "post": {
        "operationId": "recoveryLogin",
        "summary": "Issue a shared FS27 session with a recovery code.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryPayload" } } } },
        "responses": { "200": { "description": "Recovery login result" } }
      }
    },
    "/auth/forgot-password": {
      "post": {
        "operationId": "forgotPassword",
        "summary": "Request the shared gate reset email.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryPayload" } } } },
        "responses": { "200": { "description": "Reset request accepted" } }
      }
    },
    "/admin/login": {
      "post": {
        "operationId": "adminLogin",
        "summary": "Exchange the owner/admin code for the shared owner session.",
        "security": [],
        "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "format": "password" } } } } } },
        "responses": { "200": { "description": "Owner session result" } }
      }
    },
    "/auth/me": {
      "get": {
        "operationId": "me",
        "summary": "Read the current shared gate profile.",
        "responses": { "200": { "description": "Current profile" } }
      }
    },
    "/auth/introspect": {
      "post": {
        "operationId": "introspect",
        "summary": "Introspect a shared gate token.",
        "responses": { "200": { "description": "Token introspection result" } }
      }
    },
    "/auth/logout": {
      "post": {
        "operationId": "logout",
        "summary": "End the shared gate session.",
        "responses": { "200": { "description": "Logout accepted" } }
      }
    },
    "/skyepay/offers": {
      "get": {
        "operationId": "skyepayOffers",
        "summary": "Read public SkyePay offers for a client.",
        "security": [],
        "parameters": [
          { "name": "client", "in": "query", "schema": { "type": "string", "default": "metraiyux-0s" } }
        ],
        "responses": { "200": { "description": "Offer list" } }
      }
    },
    "/skyepay/checkout": {
      "post": {
        "operationId": "skyepayCheckout",
        "summary": "Create a SkyePay checkout from a Sol or embedded storefront, including artist donation/media subscription support metadata.",
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutPayload" } } } },
        "responses": { "200": { "description": "Checkout result" } }
      }
    },
    "/skyepay/status": {
      "get": {
        "operationId": "skyepayStatus",
        "summary": "Read checkout status.",
        "security": [],
        "parameters": [
          { "name": "session_id", "in": "query", "schema": { "type": "string" } },
          { "name": "demo_session", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Checkout status" } }
      }
    }
  }
}