{
  "openapi": "3.1.0",
  "info": {
    "title": "M3 Solutions Licensing API",
    "version": "1.0.0",
    "description": "Privileged Keygen credentials stay on the server. Cookie sessions are not accepted by identity API endpoints. Poll grant status after accepted issuance. License failures return valid=false and a code; transport failures never imply validity."
  },
  "servers": [
    {
      "url": "https://keygen.m3solutions.biz/api/licensing/v1"
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "summary": "Published applications and offerings",
        "operationId": "get_products",
        "security": [],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        }
      }
    },
    "/organizations": {
      "get": {
        "summary": "Organizations visible to authenticated subject",
        "operationId": "get_organizations",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        }
      }
    },
    "/trials": {
      "post": {
        "summary": "Request the subject\u2019s unique 14-day product trial",
        "operationId": "post_trials",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrialRequest"
              }
            }
          }
        }
      }
    },
    "/grants/{id}": {
      "get": {
        "summary": "Read an authorized grant and retrieve its key when ready",
        "operationId": "get_grants_id",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/installations/activate": {
      "post": {
        "summary": "Activate a product-bound installation",
        "operationId": "post_installations_activate",
        "security": [
          {
            "License": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallationRequest"
              }
            }
          }
        }
      }
    },
    "/installations/validate": {
      "post": {
        "summary": "Validate a product-bound installation",
        "operationId": "post_installations_validate",
        "security": [
          {
            "License": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallationRequest"
              }
            }
          }
        }
      }
    },
    "/installations/deactivate": {
      "post": {
        "summary": "Deactivate a product-bound installation",
        "operationId": "post_installations_deactivate",
        "security": [
          {
            "License": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallationRequest"
              }
            }
          }
        }
      }
    },
    "/installations/checkout": {
      "post": {
        "summary": "Checkout a product-bound installation",
        "operationId": "post_installations_checkout",
        "security": [
          {
            "License": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InstallationRequest"
              }
            }
          }
        }
      }
    },
    "/offline/{id}": {
      "post": {
        "summary": "Authorize transferred offline request and return signed machine certificate",
        "operationId": "post_offline_id",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OfflineRequest"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/staff/products": {
      "post": {
        "summary": "Create products",
        "operationId": "post_staff_products",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin or licensing-operator"
      }
    },
    "/staff/offerings": {
      "post": {
        "summary": "Create offerings",
        "operationId": "post_staff_offerings",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OfferingInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin or licensing-operator"
      }
    },
    "/staff/organizations": {
      "post": {
        "summary": "Create organizations",
        "operationId": "post_staff_organizations",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin or licensing-operator"
      }
    },
    "/staff/organizations/{id}/members": {
      "post": {
        "summary": "Add organization membership",
        "operationId": "post_staff_organizations_id_members",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "204": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MembershipInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/staff/organizations/{id}/members/{subject}": {
      "delete": {
        "summary": "Remove organization membership",
        "operationId": "delete_staff_organizations_id_members_subject",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "204": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "description": "Required Keycloak realm role: licensing-admin",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "subject",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/staff/grants": {
      "post": {
        "summary": "Queue license issuance",
        "operationId": "post_staff_grants",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GrantResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin or licensing-operator"
      }
    },
    "/staff/grants/{id}": {
      "patch": {
        "summary": "Change expiry/suspension or convert an offering",
        "operationId": "patch_staff_grants_id",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "204": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateGrantInput"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-admin or licensing-operator",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ]
      }
    },
    "/integrations/desired-state": {
      "post": {
        "summary": "Queue idempotent revisioned ERP desired state",
        "operationId": "post_integrations_desired-state",
        "security": [
          {
            "Bearer": []
          }
        ],
        "responses": {
          "202": {
            "description": "Success"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Insufficient role or policy restriction"
          },
          "404": {
            "description": "Resource not found or outside organization"
          },
          "409": {
            "description": "Conflict or manual review required"
          },
          "422": {
            "description": "Upstream policy rejected operation"
          },
          "429": {
            "description": "Rate limited"
          },
          "503": {
            "description": "Dependency unavailable; retry reads/reconcile intent"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErpDesiredState"
              }
            }
          }
        },
        "description": "Required Keycloak realm role: licensing-integration"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "License": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "License <license-key>"
      }
    },
    "schemas": {
      "InstallationRequest": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string",
            "maxLength": 63
          },
          "fingerprint": {
            "type": "string",
            "pattern": "^v1:[a-fA-F0-9]{64}$"
          }
        },
        "required": [
          "product",
          "fingerprint"
        ]
      },
      "OfflineRequest": {
        "type": "object",
        "properties": {
          "version": {
            "type": "integer",
            "const": 1
          },
          "product": {
            "type": "string"
          },
          "fingerprint": {
            "type": "string",
            "pattern": "^v1:[a-fA-F0-9]{64}$"
          },
          "deviceName": {
            "type": "string"
          }
        },
        "required": [
          "product",
          "fingerprint",
          "deviceName"
        ]
      },
      "ValidationResult": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "code": {
            "type": "string"
          },
          "machineId": {
            "type": [
              "string",
              "null"
            ]
          },
          "certificate": {
            "type": [
              "string",
              "null"
            ]
          },
          "licenseExpiry": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "entitlements": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "valid",
          "code"
        ]
      },
      "GrantResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "Pending",
              "Reconciling",
              "Ready"
            ]
          },
          "key": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "status"
        ]
      },
      "TrialRequest": {
        "type": "object",
        "properties": {
          "product": {
            "type": "string"
          },
          "organizationId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "product",
          "organizationId"
        ]
      },
      "ProductInput": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9-]{1,62}$"
          },
          "name": {
            "type": "string"
          },
          "published": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "slug",
          "name"
        ]
      },
      "OfferingInput": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "Trial",
              "FixedTerm",
              "Subscription",
              "Perpetual"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "StrictOnline",
              "Intermittent",
              "ActivateOnce",
              "AirGapped"
            ]
          },
          "devices": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000,
            "default": 1
          },
          "entitlements": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "productId",
          "name",
          "kind",
          "mode"
        ]
      },
      "OrganizationInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ]
      },
      "MembershipInput": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string"
          }
        },
        "required": [
          "subject"
        ]
      },
      "IssueInput": {
        "type": "object",
        "properties": {
          "organizationId": {
            "type": "string",
            "format": "uuid"
          },
          "offeringId": {
            "type": "string",
            "format": "uuid"
          },
          "paidThrough": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "requestId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Reuse the same UUID when retrying the same issuance request."
          }
        },
        "required": [
          "organizationId",
          "offeringId"
        ]
      },
      "UpdateGrantInput": {
        "type": "object",
        "properties": {
          "paidThrough": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "suspended": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "offeringId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        },
        "required": []
      },
      "ErpDesiredState": {
        "type": "object",
        "properties": {
          "eventId": {
            "type": "string"
          },
          "externalReference": {
            "type": "string"
          },
          "revision": {
            "type": "integer",
            "minimum": 0
          },
          "organizationId": {
            "type": "string",
            "format": "uuid"
          },
          "offeringId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "cancelled",
              "suspended"
            ]
          },
          "paidThrough": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "eventId",
          "externalReference",
          "revision",
          "organizationId",
          "offeringId",
          "status",
          "paidThrough"
        ]
      }
    }
  }
}