{
  "openapi": "3.1.0",
  "info": {
    "title": "Sekiwa Licensing API",
    "version": "3.0.0",
    "description": "Canonical Sekiwa licensing contract. Sekiwa is the sole licensing authority; private signing keys never leave the authority. The signed snapshot schema is version 1."
  },
  "servers": [{ "url": "https://YOUR_DEPLOYMENT.convex.site" }],
  "paths": {
    "/licensing/bridge": {
      "post": {
        "summary": "Resolve access or submit an authenticated licensing operation",
        "operationId": "licensingBridge",
        "description": "Trusted backends call this endpoint with a short-lived signed integration assertion. The assertion in the request body is the only authentication for this operation: no bearer token or API key is used, and clients must not send one. The private signing key never leaves the consumer's backend. For decommissionDevice, the assertion deviceId identifies the acting device, while the request deviceId identifies the target licensing device. OWNER or MANAGER role is required. requestDevice answers 409 DESTINATION_ALREADY_ACTIVE when the destination device already holds an active slot; that duplicate request is closed. Setup and error codes: cloud/docs/integration-keys.md.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeRequest" } } }
        },
        "responses": {
          "200": { "description": "Access decision, request status, device-request list, or device-decommission result (including no-op responses)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeResponse" } } } },
          "201": { "description": "Device request created. On a live free licence (a billing option the catalogue marks free) a NEW_SLOT request from the OWNER who asked for it is approved in the same call, up to the licence's device limit, and is returned with status APPROVED; any other request is returned PENDING for the owner to decide.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceRequest" } } } },
          "202": { "description": "Entitlement request accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BridgeResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "413": { "$ref": "#/components/responses/PayloadTooLarge" },
          "500": { "$ref": "#/components/responses/ServerError" },
          "503": { "$ref": "#/components/responses/ServiceUnavailable" }
        }
      },
      "options": { "$ref": "#/components/pathItems/Options" }
    },
    "/licensing/experience": {
      "get": {
        "summary": "Read the declarative licensing experience",
        "operationId": "getLicensingExperience",
        "parameters": [
          { "$ref": "#/components/parameters/ApplicationId" },
          { "$ref": "#/components/parameters/Environment" }
        ],
        "responses": {
          "200": { "description": "Public experience configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicExperienceResponse" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      },
      "options": { "$ref": "#/components/pathItems/Options" }
    },
    "/v1/cli/auth/device/start": {
      "post": { "summary": "Start CLI device authorization", "operationId": "startCliDeviceAuthorization", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationStartRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/auth/device/poll": {
      "post": { "summary": "Poll CLI device authorization", "operationId": "pollCliDeviceAuthorization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationPollRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/auth/refresh": {
      "post": { "summary": "Refresh CLI session", "operationId": "refreshCliSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliRefreshRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/auth/logout": {
      "post": { "summary": "Log out a CLI session", "description": "A session client may include its refresh token so logout can revoke the session family if a concurrent refresh rotates the access token. The refresh token is sensitive and must only be sent over HTTPS.", "operationId": "logoutCliSession", "security": [{ "BearerAuth": [] }, {}], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogoutRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/me": {
      "get": { "summary": "Read the authenticated CLI account", "operationId": "getCliAccount", "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }
    },
    "/v1/cli/workspaces": {
      "get": { "summary": "List CLI workspaces", "operationId": "listCliWorkspaces", "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" } } },
      "post": { "summary": "Create a CLI workspace", "operationId": "createCliWorkspace", "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/workspaces/{workspaceId}/apps": {
      "get": { "summary": "List workspace applications", "operationId": "listCliApps", "parameters": [{ "$ref": "#/components/parameters/WorkspaceId" }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "post": { "summary": "Create a workspace application", "operationId": "createCliApp", "parameters": [{ "$ref": "#/components/parameters/WorkspaceId" }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/cli/workspaces/{workspaceId}/setup": {
      "post": { "summary": "Apply an idempotent workspace setup manifest", "operationId": "setupCliWorkspace", "parameters": [{ "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/IdempotencyKey" }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceSetupRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/workspaces/{workspaceId}/requests": {
      "get": { "summary": "List entitlement requests", "operationId": "listCliEntitlementRequests", "parameters": [{ "$ref": "#/components/parameters/WorkspaceId" }, { "name": "environment", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/Environment" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }}
    },
    "/v1/cli/workspaces/{workspaceId}/requests/{requestId}/decision": {
      "post": { "summary": "Approve or deny an entitlement request", "operationId": "decideCliEntitlementRequest", "description": "Workspace owner or admin only. Approval reuses the canonical grant path, so the entitlement, device request, and signed snapshot are produced identically to the dashboard review.", "parameters": [{ "$ref": "#/components/parameters/WorkspaceId" }, { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string" } }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequestDecision" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/apps/{appId}": {
      "get": { "summary": "Read an application and its public licensing configuration", "operationId": "getCliApp", "parameters": [{ "$ref": "#/components/parameters/AppId" }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }}
    },
    "/v1/cli/apps/{appId}/experience": {
      "get": { "summary": "Read customer-facing experience configuration and plan visibility", "operationId": "getCliExperience", "parameters": [{ "$ref": "#/components/parameters/AppId" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": ["base", "development", "production"], "default": "development" } }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }}
    },
    "/v1/cli/apps/{appId}/experience/plans": {
      "patch": { "summary": "Set customer-visible plan codes", "operationId": "setCliExperienceVisiblePlans", "description": "Requires apps:write and workspace owner/admin membership. App- and environment-bound credentials can only write within their approved scope; environment-bound credentials cannot write the shared base config.", "parameters": [{ "$ref": "#/components/parameters/AppId" }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliExperiencePlanVisibilityInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }}
    },
    "/v1/cli/apps/{appId}/plans": {
      "get": { "summary": "List application plans", "operationId": "listCliPlans", "parameters": [{ "$ref": "#/components/parameters/AppId" }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "post": { "summary": "Create an application plan", "operationId": "createCliPlan", "parameters": [{ "$ref": "#/components/parameters/AppId" }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliPlanInput" } } } }, "responses": { "201": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/apps/{appId}/plans/{planCode}": {
      "parameters": [{ "$ref": "#/components/parameters/AppId" }, { "$ref": "#/components/parameters/PlanCode" }],
      "get": { "summary": "Read an application plan", "operationId": "getCliPlan", "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } },
      "patch": { "summary": "Update an application plan", "operationId": "updateCliPlan", "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliPlanInput" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } } },
      "delete": { "summary": "Delete an application plan after code confirmation", "operationId": "deleteCliPlan", "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanDeleteRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/apps/{appId}/environments": {
      "get": { "summary": "List application environments and release gate state", "operationId": "listCliAppEnvironments", "parameters": [{ "$ref": "#/components/parameters/AppId" }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }
    },
    "/v1/cli/apps/{appId}/environments/{environment}/release": {
      "post": { "summary": "Advance an application environment release gate", "operationId": "setCliAppEnvironmentRelease", "description": "Production transitions require the workspace owner; enabling requires a prior readiness approval carrying a release reason, ticket, and release id.", "parameters": [{ "$ref": "#/components/parameters/AppId" }, { "name": "environment", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } }], "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentReleaseRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/keys": {
      "get": { "summary": "List workspace API key metadata (owner/admin only)", "operationId": "listCliKeys", "security": [{ "BearerAuth": [] }], "parameters": [{ "name": "workspace", "in": "query", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } },
      "post": { "summary": "Create a workspace API key", "operationId": "createCliKey", "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CliKeyCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "413": { "$ref": "#/components/responses/Json" } }}
    },
    "/v1/cli/keys/{keyId}": {
      "delete": { "summary": "Revoke a workspace API key", "operationId": "revokeCliKey", "parameters": [{ "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": true, "schema": { "type": "string" } }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }}
    },
    "/v1/cli/keys/{keyId}/rotate": {
      "post": { "summary": "Rotate a workspace API key", "operationId": "rotateCliKey", "parameters": [{ "name": "keyId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspace", "in": "query", "required": true, "schema": { "type": "string" } }], "security": [{ "BearerAuth": [] }], "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }}
    },
    "/v1/entitlements/extend": {
      "post": { "summary": "Queue a privileged explicit entitlement-term extension", "operationId": "extendEntitlementTerm", "description": "Server-to-server only. Requires a revocable API key bound to one application and environment with the entitlements:extend scope. A normal licensing bridge assertion is not accepted. Same scoped externalReference and identical body returns the existing request; conflicting reuse fails. The response is queued until the authoritative revision and replacement v1 snapshots are signed atomically.", "security": [{ "BearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermExtensionRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "202": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/Json" } } }
    },
    "/v1/reachout/referrer": {
      "post": { "summary": "Create or read a referral identity", "operationId": "getOrCreateReferrer", "description": "Requires a REFERRAL assertion signed by the vendor backend for the same appId. Its businessId and deviceId are the only identities the caller may act as.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachoutIdentityRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "options": { "$ref": "#/components/pathItems/Options" } }
    },
    "/v1/reachout/validate": {
      "post": { "summary": "Validate and record a referral", "operationId": "validateReferral", "description": "Requires a REFERRAL assertion signed by the vendor backend for the same appId. Its businessId and deviceId are the only identities the caller may act as.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachoutValidateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "options": { "$ref": "#/components/pathItems/Options" } }
    },
    "/v1/reachout/list": {
      "post": { "summary": "List referrals for the asserted identity", "operationId": "listReferrals", "description": "Requires a REFERRAL assertion signed by the vendor backend for the same appId. Its businessId and deviceId are the only identities the caller may act as.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachoutIdentityRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "options": { "$ref": "#/components/pathItems/Options" } }
    },
    "/v1/reachout/activation": {
      "post": { "summary": "Confirm a referral activation event", "operationId": "confirmReferralActivation", "description": "Requires a REFERRAL assertion signed by the vendor backend for the same appId. Its businessId and deviceId are the only identities the caller may act as.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReachoutActivationRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/Json" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/Json" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "options": { "$ref": "#/components/pathItems/Options" } }
    }
  },
  "components": {
    "pathItems": {
      "Options": {
        "options": { "summary": "CORS preflight", "responses": { "204": { "description": "Preflight accepted" }, "403": { "description": "Origin is not allowed" } } }
      }
    },
    "parameters": {
      "ApplicationId": { "name": "applicationId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } },
      "Environment": { "name": "environment", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Environment" } },
      "AppId": { "name": "appId", "in": "path", "required": true, "schema": { "type": "string" } },
      "WorkspaceId": { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } },
      "PlanCode": { "name": "planCode", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80 } },
      "IdempotencyKey": { "name": "idempotency-key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }
    },
    "securitySchemes": {
      "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Sekiwa API key or CLI access token" }
    },
    "responses": {
      "Json": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
      "BadRequest": { "description": "Request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Authentication or trusted integration assertion is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "The caller is not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "The request conflicts with current authority state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "The requested licensing resource is not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "PayloadTooLarge": { "description": "The request body exceeds the licensing bridge limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ServerError": { "description": "The request could not be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "ServiceUnavailable": { "description": "A required licensing service or configuration is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": { "description": "Retry after the server-provided delay", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    },
    "schemas": {
      "Environment": { "type": "string", "enum": ["development", "production"] },
      "DeviceAuthorizationStartRequest": { "type": "object", "properties": { "clientName": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false },
      "DeviceAuthorizationPollRequest": { "type": "object", "required": ["deviceCode"], "properties": { "deviceCode": { "type": "string", "minLength": 1, "maxLength": 512 } }, "additionalProperties": false },
      "CliRefreshRequest": { "type": "object", "required": ["refreshToken"], "properties": { "refreshToken": { "type": "string", "minLength": 20, "maxLength": 200 } }, "additionalProperties": false },
      "WorkspaceCreateRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" } }, "additionalProperties": false },
      "ApplicationCreateRequest": { "type": "object", "required": ["name", "identifier"], "properties": { "name": { "type": "string" }, "identifier": { "type": "string" }, "activationMode": { "type": "string", "enum": ["online", "offline", "hybrid"] } }, "additionalProperties": false },
      "CliExperiencePlanVisibilityInput": { "type": "object", "required": ["scope", "visiblePlanCodes"], "properties": { "scope": { "type": "string", "enum": ["base", "development", "production"] }, "visiblePlanCodes": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 80 } } }, "additionalProperties": false },
      "CliPlanInput": { "type": "object", "required": ["code", "name", "durationDays", "graceDays", "maxDevices", "features"], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "durationDays": { "type": "number" }, "graceDays": { "type": "number" }, "maxDevices": { "type": "number" }, "features": { "type": "array", "items": { "type": "string" } }, "isTrial": { "type": "boolean" }, "enabled": { "type": "boolean" }, "price": { "type": "number" }, "limits": { "type": "object", "additionalProperties": true }, "billingOptions": { "type": "array", "items": { "type": "object", "required": ["id", "cadence"], "properties": { "id": { "type": "string" }, "cadence": { "type": "string", "enum": ["monthly", "yearly", "custom"] }, "durationDays": { "type": "number" }, "price": { "type": "number" }, "currency": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false } }, "activationMode": { "type": "string", "enum": ["SELF_SERVICE", "MANAGED"] } }, "additionalProperties": false },
      "SetupPlan": { "type": "object", "required": ["code", "name", "features"], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "durationDays": { "type": "number" }, "graceDays": { "type": "number" }, "maxDevices": { "type": "number" }, "features": { "type": "array", "items": { "type": "string" } }, "isTrial": { "type": "boolean" }, "enabled": { "type": "boolean" }, "price": { "type": "number" }, "limits": { "type": "object", "additionalProperties": true }, "billingOptions": { "type": "array", "items": { "type": "object", "required": ["id", "cadence"], "properties": { "id": { "type": "string" }, "cadence": { "type": "string", "enum": ["monthly", "yearly", "custom"] }, "durationDays": { "type": "number" }, "price": { "type": "number" }, "currency": { "type": "string" }, "enabled": { "type": "boolean" } }, "additionalProperties": false } }, "activationMode": { "type": "string", "enum": ["SELF_SERVICE", "MANAGED"] } }, "additionalProperties": false },
      "WorkspaceSetupManifest": { "type": "object", "required": ["app", "plans"], "properties": { "schemaVersion": { "const": 1 }, "workspace": { "type": "string" }, "app": { "type": "object", "required": ["name", "identifier"], "properties": { "name": { "type": "string" }, "identifier": { "type": "string" }, "activationMode": { "type": "string", "enum": ["online", "offline", "hybrid"] } }, "additionalProperties": false }, "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } }, "features": { "type": "array", "items": { "type": "string" } }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/SetupPlan" } } }, "additionalProperties": false },
      "WorkspaceSetupRequest": { "type": "object", "required": ["manifest"], "properties": { "manifest": { "$ref": "#/components/schemas/WorkspaceSetupManifest" }, "allowPlanUpdates": { "type": "boolean" }, "allowPlanRemovals": { "type": "boolean" } }, "additionalProperties": false },
      "PlanDeleteRequest": { "type": "object", "required": ["confirmation"], "properties": { "confirmation": { "type": "string" } }, "additionalProperties": false },
      "CliKeyCreateRequest": { "type": "object", "required": ["workspace", "name"], "properties": { "workspace": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "applicationId": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "expiresAt": { "type": "integer" } }, "additionalProperties": false },
      "ReachoutIdentityRequest": { "type": "object", "required": ["appId", "assertion", "customerName"], "properties": { "appId": { "type": "string", "maxLength": 80 }, "assertion": { "type": "string", "maxLength": 16384, "description": "Signed REFERRAL trusted-integration assertion. The vendor private key must remain server-side." }, "customerName": { "type": "string", "minLength": 1, "maxLength": 120 }, "businessName": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "maxLength": 256 }, "phone": { "type": "string", "maxLength": 256 }, "customerId": { "type": "string", "maxLength": 200 }, "deviceId": { "type": "string", "maxLength": 200 }, "businessId": { "type": "string", "maxLength": 200 }, "localBusinessId": { "type": "string", "maxLength": 200 } }, "additionalProperties": false },
      "ReachoutValidateRequest": { "type": "object", "required": ["appId", "assertion", "customerName", "referralCode"], "properties": { "appId": { "type": "string", "maxLength": 80 }, "assertion": { "type": "string", "maxLength": 16384, "description": "Signed REFERRAL trusted-integration assertion. The vendor private key must remain server-side." }, "customerName": { "type": "string", "minLength": 1, "maxLength": 120 }, "businessName": { "type": "string", "maxLength": 120 }, "email": { "type": "string", "maxLength": 256 }, "phone": { "type": "string", "maxLength": 256 }, "customerId": { "type": "string", "maxLength": 200 }, "deviceId": { "type": "string", "maxLength": 200 }, "businessId": { "type": "string", "maxLength": 200 }, "localBusinessId": { "type": "string", "maxLength": 200 }, "referralCode": { "type": "string", "minLength": 1, "maxLength": 64 } }, "additionalProperties": false },
      "ReachoutActivationRequest": { "type": "object", "required": ["appId", "assertion", "eventId"], "properties": { "appId": { "type": "string", "maxLength": 80 }, "assertion": { "type": "string", "maxLength": 16384, "description": "Signed REFERRAL trusted-integration assertion. The vendor private key must remain server-side." }, "businessId": { "type": "string", "maxLength": 200 }, "localBusinessId": { "type": "string", "maxLength": 200 }, "deviceId": { "type": "string", "maxLength": 200 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 200 }, "licenseId": { "type": "string", "maxLength": 256 }, "referralCode": { "type": "string", "maxLength": 64 }, "customerName": { "type": "string", "maxLength": 120 }, "activatedAt": { "type": "string", "maxLength": 256 }, "notes": { "type": "string", "maxLength": 256 } }, "additionalProperties": false },
      "EnvironmentReleaseRequest": { "type": "object", "required": ["state", "confirmation"], "properties": { "state": { "type": "string", "enum": ["ready", "enabled", "disabled"] }, "confirmation": { "type": "string", "enum": ["MARK PRODUCTION READY", "ENABLE PRODUCTION", "DISABLE PRODUCTION"] }, "reviewWorkflow": { "type": "string", "enum": ["direct-review", "payment-verification-first"] }, "releaseReason": { "type": "string" }, "ticketReference": { "type": "string" }, "releaseId": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": false },
      "EntitlementRequestDecision": { "type": "object", "required": ["decision"], "properties": { "decision": { "type": "string", "enum": ["approve", "deny"] }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000 }, "internalNote": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false },
      "LogoutRequest": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 20, "maxLength": 200, "description": "Optional session refresh token used to revoke its family when the access token was rotated during logout." } }, "additionalProperties": false },
      "TermExtensionRequest": { "type": "object", "required": ["entitlementId", "externalReference", "source", "durationUnit", "durationCount"], "properties": { "entitlementId": { "type": "string" }, "externalReference": { "type": "string", "minLength": 8, "maxLength": 160 }, "source": { "type": "string", "minLength": 1, "maxLength": 80 }, "reason": { "type": "string", "maxLength": 300 }, "durationUnit": { "type": "string", "enum": ["days", "months"] }, "durationCount": { "type": "integer", "minimum": 1, "maximum": 120 } }, "additionalProperties": false },
      "LicenseeReference": { "type": "object", "required": ["type", "externalId"], "properties": { "type": { "type": "string", "enum": ["USER", "BUSINESS", "ORGANIZATION", "ACCOUNT", "CUSTOM"] }, "externalId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false },
      "BridgeRequest": { "type": "object", "required": ["operation", "assertion"], "properties": { "operation": { "type": "string", "enum": ["resolve", "requestEntitlement", "cancelEntitlementRequest", "requestDevice", "decommissionDevice", "decideDeviceRequest", "pollDeviceRequest", "listDeviceRequests", "escalateRecovery", "receiptAcknowledgement"] }, "assertion": { "type": "string", "description": "JSON-serialized signed trusted integration assertion; keep its private key on the backend." }, "requestId": { "type": "string" }, "idempotencyKey": { "type": "string" }, "requestedPlanCode": { "type": "string" }, "billingOptionId": { "type": "string" }, "purpose": { "type": "string" }, "restoreExisting": { "type": "boolean" }, "lostDevice": { "type": "boolean" }, "customerName": { "type": "string" }, "customerEmail": { "type": "string" }, "deviceName": { "type": "string" }, "devicePlatform": { "type": "string" }, "pauseBindingIds": { "type": "array", "items": { "type": "string" } }, "requestType": { "type": "string", "enum": ["NEW_SLOT", "REPLACEMENT", "RECOVERY"] }, "destinationDeviceId": { "type": "string" }, "deviceId": { "type": "string", "minLength": 3, "maxLength": 200, "description": "Target licensing device for decommissionDevice; the assertion deviceId identifies the actor." }, "sourceBindingId": { "type": "string" }, "entitlementId": { "type": "string", "description": "Optional entitlement scope for decommissionDevice." }, "decision": { "type": "string", "enum": ["APPROVE", "DENY"] }, "reason": { "type": "string" }, "receiptId": { "type": "string" }, "snapshotId": { "type": "string" }, "snapshotHash": { "type": "string" }, "appliedAt": { "type": "integer" } }, "additionalProperties": false },
      "BridgeResponse": { "type": "object", "additionalProperties": true },
      "Entitlement": { "type": "object", "required": ["id", "licenseeId", "appId", "environment", "mode", "lifecycle", "currentRevision", "planCode", "features", "limits", "validFrom", "capacity"], "properties": { "id": { "type": "string" }, "licenseeId": { "type": "string" }, "appId": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "mode": { "type": "string", "enum": ["ONLINE", "OFFLINE"] }, "lifecycle": { "type": "string", "enum": ["ACTIVE", "GRACE", "EXPIRED", "SUSPENDED", "REVOKED"] }, "currentRevision": { "type": "integer", "minimum": 1 }, "planCode": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": true }, "validFrom": { "type": "integer" }, "expiresAt": { "type": "integer" }, "graceEndsAt": { "type": "integer" }, "capacity": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
      "EntitlementRevision": { "type": "object", "required": ["id", "entitlementId", "revision", "operation", "planCode", "features", "limits", "validFrom", "source", "createdAt"], "properties": { "id": { "type": "string" }, "entitlementId": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "operation": { "type": "string", "enum": ["CREATE", "RENEW", "UPGRADE", "DOWNGRADE", "REACTIVATE", "REVOKE"] }, "planCode": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": true }, "validFrom": { "type": "integer" }, "expiresAt": { "type": "integer" }, "graceEndsAt": { "type": "integer" }, "actorId": { "type": "string" }, "source": { "type": "string", "enum": ["VENDOR", "TRUSTED_INTEGRATION", "OFFLINE_FILE", "SYSTEM"] }, "priorRevision": { "type": "integer" }, "createdAt": { "type": "integer" } }, "additionalProperties": false },
      "DeviceBinding": { "type": "object", "required": ["id", "entitlementId", "licenseeId", "appId", "environment", "deviceId", "lifecycle", "boundAt"], "properties": { "id": { "type": "string" }, "entitlementId": { "type": "string" }, "licenseeId": { "type": "string" }, "appId": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "deviceId": { "type": "string" }, "lifecycle": { "type": "string", "enum": ["ACTIVE", "REPLACED", "REVOKED"] }, "boundAt": { "type": "integer" }, "replacedAt": { "type": "integer" }, "revokedAt": { "type": "integer" }, "replacedByBindingId": { "type": "string" }, "replacesBindingId": { "type": "string" }, "lastSeenAt": { "type": "integer" } }, "additionalProperties": false },
      "DeviceRequest": { "type": "object", "required": ["id", "entitlementId", "licenseeId", "appId", "environment", "type", "status", "generation", "idempotencyKey", "destinationDeviceId", "createdAt", "expiresAt", "ownerConfirmationRequired"], "properties": { "id": { "type": "string" }, "entitlementId": { "type": "string" }, "licenseeId": { "type": "string" }, "appId": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "type": { "type": "string", "enum": ["NEW_SLOT", "REPLACEMENT", "RECOVERY"] }, "status": { "type": "string", "enum": ["PENDING", "APPROVED", "DENIED", "EXPIRED", "FAILED"] }, "generation": { "type": "integer", "minimum": 1 }, "idempotencyKey": { "type": "string" }, "destinationDeviceId": { "type": "string" }, "sourceBindingId": { "type": "string" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "requestedByActorId": { "type": "string" }, "ownerConfirmationRequired": { "type": "boolean" }, "decision": { "type": "object", "additionalProperties": true } }, "additionalProperties": false },
      "SignedLicenseSnapshotPayload": { "type": "object", "required": ["schemaVersion", "snapshotId", "licensee", "appId", "environment", "mode", "entitlementId", "entitlementRevision", "bindingId", "deviceId", "lifecycle", "decision", "planCode", "features", "limits", "issuedAt", "validFrom", "keyId"], "properties": { "schemaVersion": { "const": 1 }, "snapshotId": { "type": "string" }, "licensee": { "$ref": "#/components/schemas/LicenseeReference" }, "appId": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" }, "mode": { "type": "string", "enum": ["ONLINE", "OFFLINE"] }, "entitlementId": { "type": "string" }, "entitlementRevision": { "type": "integer", "minimum": 1 }, "bindingId": { "type": "string" }, "deviceId": { "type": "string" }, "lifecycle": { "type": "string", "enum": ["ACTIVE", "GRACE", "EXPIRED", "SUSPENDED", "REVOKED"] }, "decision": { "type": "string", "enum": ["ALLOW", "BLOCK"] }, "planCode": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": true }, "issuedAt": { "type": "integer" }, "validFrom": { "type": "integer" }, "expiresAt": { "type": "integer" }, "graceEndsAt": { "type": "integer" }, "revalidateBy": { "type": "integer" }, "keyId": { "type": "string" } }, "additionalProperties": false },
      "SignedLicenseSnapshot": { "type": "object", "required": ["schemaVersion", "payload", "keyId", "signature"], "properties": { "schemaVersion": { "const": 1 }, "payload": { "$ref": "#/components/schemas/SignedLicenseSnapshotPayload" }, "keyId": { "type": "string" }, "signature": { "type": "string" } }, "additionalProperties": false },
      "PublicExperienceResponse": { "type": "object", "required": ["schemaVersion", "application", "experience", "visiblePlans", "generatedAt"], "properties": { "schemaVersion": { "const": 1 }, "application": { "type": "object", "required": ["id", "environment"], "properties": { "id": { "type": "string" }, "environment": { "$ref": "#/components/schemas/Environment" } }, "additionalProperties": false }, "experience": { "type": "object", "description": "Declarative text, color, plan, field, and action configuration; remote code and CSS are not accepted." }, "visiblePlans": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "generatedAt": { "type": "integer" }, "revision": { "type": "string" } }, "additionalProperties": false },
      "Error": { "oneOf": [{ "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false } }, "additionalProperties": false }] }
    }
  }
}