{
  "components": {
    "schemas": {
      "ExternalCapabilities": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "delivery_types": {
            "items": {
              "enum": [
                "license_key",
                "activation_url",
                "instructions"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          },
          "devices": {
            "const": false,
            "type": "boolean"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "identity_exchange": {
            "const": false,
            "type": "boolean"
          },
          "protocol": {
            "const": "launch-external-licensing-v1",
            "type": "string"
          },
          "purchase_types": {
            "items": {
              "enum": [
                "perpetual",
                "fixed_term"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "protocol",
          "connection_ref",
          "environment",
          "purchase_types",
          "delivery_types"
        ],
        "type": "object"
      },
      "ExternalCapabilitiesResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalCapabilities"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalDelivery": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "delivery": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ExternalDeliveryValue"
              },
              {
                "type": "null"
              }
            ]
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "ready",
              "unavailable"
            ],
            "type": "string"
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "connection_ref",
          "environment",
          "entitlement_ref",
          "version",
          "status",
          "delivery"
        ],
        "type": "object"
      },
      "ExternalDeliveryResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalDelivery"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalDeliveryValue": {
        "additionalProperties": false,
        "properties": {
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "enum": [
              "license_key",
              "activation_url",
              "instructions"
            ],
            "type": "string"
          },
          "value": {
            "description": "Sensitive; maximum 4096 UTF-8 bytes. Never log. Activation URLs must use a configured HTTPS origin.",
            "maxLength": 4096,
            "type": "string"
          }
        },
        "required": [
          "type",
          "value",
          "expires_at"
        ],
        "type": "object"
      },
      "ExternalError": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "error",
          "request_id"
        ],
        "type": "object"
      },
      "ExternalReceipt": {
        "additionalProperties": false,
        "properties": {
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "error_code": {
            "anyOf": [
              {
                "maxLength": 96,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "event_id": {
            "format": "uuid",
            "type": "string"
          },
          "payload_sha256": {
            "pattern": "^[0-9a-f]{64}$",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "applied",
              "rejected",
              "manual_review"
            ],
            "type": "string"
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "event_id",
          "connection_ref",
          "environment",
          "entitlement_ref",
          "version",
          "payload_sha256",
          "status",
          "error_code"
        ],
        "type": "object"
      },
      "ExternalReceiptResponse": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ExternalReceipt"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ExternalSnapshot": {
        "additionalProperties": false,
        "properties": {
          "account_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "change_reason": {
            "enum": [
              "purchase",
              "renewal",
              "upgrade",
              "refund",
              "reversal",
              "suspension",
              "resumption",
              "expiry",
              "reconciliation"
            ],
            "type": "string"
          },
          "connection_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "desired_state": {
            "enum": [
              "active",
              "suspended",
              "expired",
              "revoked"
            ],
            "type": "string"
          },
          "entitlement_ref": {
            "pattern": "^[A-Za-z0-9_-]{1,128}$",
            "type": "string"
          },
          "environment": {
            "enum": [
              "sandbox",
              "live"
            ],
            "type": "string"
          },
          "event_id": {
            "format": "uuid",
            "type": "string"
          },
          "launch_plan_version_id": {
            "format": "uuid",
            "type": "string"
          },
          "launch_product_id": {
            "format": "uuid",
            "type": "string"
          },
          "plan_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "product_ref": {
            "pattern": "^[A-Za-z0-9_.-]{1,128}$",
            "type": "string"
          },
          "schema": {
            "const": "launch-external-licensing-v1",
            "type": "string"
          },
          "type": {
            "const": "entitlement.snapshot",
            "type": "string"
          },
          "valid_from": {
            "format": "date-time",
            "type": "string"
          },
          "valid_until": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "schema",
          "event_id",
          "connection_ref",
          "environment",
          "type",
          "change_reason",
          "account_ref",
          "entitlement_ref",
          "launch_product_id",
          "launch_plan_version_id",
          "product_ref",
          "plan_ref",
          "version",
          "desired_state",
          "valid_from",
          "valid_until"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Implemented by the merchant licensing service, called by Launch. This is a commercial-state protocol, not a license generator or runtime SDK. Exact request bytes are signed; retries preserve the event ID and payload. Read the accompanying integration guide.",
    "title": "Launch External Licensing Bridge",
    "version": "1.0.0",
    "x-document-language": "en"
  },
  "openapi": "3.1.0",
  "paths": {
    "/launch/v1/capabilities": {
      "get": {
        "operationId": "externalCapabilities",
        "parameters": [
          {
            "description": "The configured key ID.",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Decimal Unix seconds, within +/-300 seconds.",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "At least 16 random bytes, base64url without padding; deduplicate for 600 seconds.",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request)); see the integration guide for exact bytes.",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalCapabilitiesResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Invalid signature or timestamp"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Connection/environment mismatch"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Replay, idempotency or state conflict"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Rate limited; respect Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Temporarily unavailable"
          }
        },
        "summary": "Validate the connection and supported protocol"
      }
    },
    "/launch/v1/entitlements/{entitlement_ref}/delivery": {
      "get": {
        "operationId": "getExternalDelivery",
        "parameters": [
          {
            "description": "The configured key ID.",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Decimal Unix seconds, within +/-300 seconds.",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "At least 16 random bytes, base64url without padding; deduplicate for 600 seconds.",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request)); see the integration guide for exact bytes.",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "entitlement_ref",
            "required": true,
            "schema": {
              "pattern": "^[A-Za-z0-9_-]{1,128}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalDeliveryResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Invalid signature or timestamp"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Connection/environment mismatch"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "No such purchase"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Replay, idempotency or state conflict"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Rate limited; respect Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Temporarily unavailable"
          }
        },
        "summary": "Read existing delivery; never create another license"
      }
    },
    "/launch/v1/events": {
      "post": {
        "operationId": "submitExternalPurchase",
        "parameters": [
          {
            "description": "The configured key ID.",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Decimal Unix seconds, within +/-300 seconds.",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "At least 16 random bytes, base64url without padding; deduplicate for 600 seconds.",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request)); see the integration guide for exact bytes.",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalSnapshot"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "Existing event or synchronously applied result"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "Durably accepted; pending is not fulfillment"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Invalid signature or timestamp"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Connection/environment mismatch"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Replay, idempotency or state conflict"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Unknown plan or unsupported purchase type"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Rate limited; respect Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Temporarily unavailable"
          }
        },
        "summary": "Persist a complete absolute purchase snapshot; do not issue twice"
      }
    },
    "/launch/v1/events/{event_id}": {
      "get": {
        "operationId": "getExternalEvent",
        "parameters": [
          {
            "description": "The configured key ID.",
            "in": "header",
            "name": "X-Launch-Key-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Decimal Unix seconds, within +/-300 seconds.",
            "in": "header",
            "name": "X-Launch-Timestamp",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "At least 16 random bytes, base64url without padding; deduplicate for 600 seconds.",
            "in": "header",
            "name": "X-Launch-Nonce",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "v1=base64url(HMAC-SHA256(key, canonical request)); see the integration guide for exact bytes.",
            "in": "header",
            "name": "X-Launch-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "event_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalReceiptResponse"
                }
              }
            },
            "description": "Successful response"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Invalid signature or timestamp"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Connection/environment mismatch"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "EVENT_NOT_FOUND: only this result permits resubmitting the original event"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Replay, idempotency or state conflict"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Rate limited; respect Retry-After"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalError"
                }
              }
            },
            "description": "Temporarily unavailable"
          }
        },
        "summary": "Recover/query the original event receipt"
      }
    }
  },
  "servers": [
    {
      "url": "https://licenses.example.com"
    }
  ]
}