{ "components": { "schemas": { "Checkout": { "allOf": [ { "$ref": "#/components/schemas/Order" }, { "properties": { "checkout_url": { "format": "uri", "type": "string" }, "fulfillment": { "type": "string" } }, "required": [ "fulfillment" ], "type": "object" } ] }, "Credential": { "properties": { "license_key": { "description": "For the official SDK only; never authorize access by inspecting this value.", "type": "string", "x-sensitive": true }, "product_id": { "format": "uuid", "type": "string" }, "valid_until": { "format": "date-time", "type": [ "string", "null" ] }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "product_id", "license_key", "valid_until", "version" ], "type": "object" }, "EntitlementStatus": { "properties": { "account_url": { "format": "uri", "type": "string" }, "code": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "max_retry_attempts": { "minimum": 0, "type": "integer" }, "message": { "type": "string" }, "next_action": { "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "retry_after_seconds": { "minimum": 0, "type": "integer" }, "status": { "enum": [ "ready", "pending", "expired", "suspended", "not_purchased" ], "type": "string" }, "synchronized": { "type": "boolean" }, "valid_from": { "format": "date-time", "type": [ "string", "null" ] }, "valid_until": { "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "product_id", "environment", "status", "code", "message", "next_action", "account_url", "synchronized", "retry_after_seconds", "max_retry_attempts" ], "type": "object" }, "Error": { "properties": { "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "error", "request_id" ], "type": "object" }, "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" }, "ExternalConnection": { "additionalProperties": false, "properties": { "activation_origins": { "items": { "format": "uri", "type": "string" }, "type": "array" }, "allow_local_http": { "type": "boolean" }, "allow_private_network": { "type": "boolean" }, "base_url": { "format": "uri", "type": "string" }, "capabilities": { "$ref": "#/components/schemas/ExternalCapabilities" }, "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "credential_stored": { "type": "boolean" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "id": { "format": "uuid", "type": "string" }, "key_id": { "type": "string" }, "last_check_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_checked_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "provider": { "const": "custom_http", "type": "string" } }, "required": [ "id", "provider", "name", "base_url", "environment", "connection_ref", "key_id", "credential_stored", "allow_private_network", "allow_local_http", "activation_origins", "capabilities", "last_checked_at", "last_check_error" ], "type": "object" }, "ExternalConnectionInput": { "additionalProperties": false, "properties": { "activation_origins": { "items": { "format": "uri", "type": "string" }, "type": "array" }, "allow_local_http": { "default": false, "description": "Only sandbox loopback HTTP is permitted.", "type": "boolean" }, "allow_private_network": { "default": false, "type": "boolean" }, "base_url": { "format": "uri", "maxLength": 512, "type": "string" }, "connection_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "key_id": { "maxLength": 64, "minLength": 1, "type": "string" }, "name": { "maxLength": 160, "minLength": 2, "type": "string" }, "provider": { "const": "custom_http", "type": "string" }, "signing_key": { "description": "Standard Base64 of 32-128 random bytes; required on create, empty retains existing key on edit.", "maxLength": 180, "type": "string", "writeOnly": true } }, "required": [ "provider", "name", "base_url", "environment", "connection_ref", "key_id" ], "type": "object" }, "ExternalConnectionResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/ExternalConnection" }, "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" }, "ExternalMapping": { "additionalProperties": false, "properties": { "connection_id": { "format": "uuid", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "plan_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "product_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "version_id": { "format": "uuid", "type": "string" } }, "required": [ "version_id", "environment", "connection_id", "product_ref", "plan_ref" ], "type": "object" }, "ExternalMappingInput": { "additionalProperties": false, "properties": { "plan_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "product_ref": { "pattern": "^[A-Za-z0-9_.-]{1,128}$", "type": "string" }, "version_id": { "format": "uuid", "type": "string" } }, "required": [ "version_id", "product_ref", "plan_ref" ], "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" }, "HealthResponse": { "properties": { "data": { "properties": { "status": { "const": "ok" } }, "required": [ "status" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" }, "IntegrationBundle": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "checks": { "items": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string" } }, "required": [ "code", "status", "message" ], "type": "object" }, "type": "array" }, "config": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "launch_product_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "const": "" } ], "description": "Empty only when a failed check could not resolve a mapping." }, "merchant_origin": { "format": "uri", "type": "string" }, "schema_version": { "const": 1, "type": "integer" } }, "required": [ "schema_version", "merchant_origin", "launch_product_id", "licentivo_product_id", "environment" ], "type": "object" }, "example_path": { "type": "string" }, "language": { "enum": [ "go", "python", "csharp", "java", "javascript", "rust", "ruby", "c", "cpp", "web" ], "type": "string" }, "product_config": { "$ref": "#/components/schemas/PublicProductConfig" }, "ready": { "type": "boolean" } }, "required": [ "ready", "config", "checks", "language", "example_path", "checked_at" ], "type": "object" }, "LaunchIdentity": { "additionalProperties": false, "properties": { "audience": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "identity_token": { "description": "Short-lived identity assertion, at most 120 seconds; never a runtime grant.", "type": "string" }, "launch_connection_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "token_type": { "type": "string" } }, "required": [ "identity_token", "token_type", "product_id", "licentivo_product_id", "launch_connection_id", "environment", "audience", "expires_at" ], "type": "object" }, "LicensingConnections": { "additionalProperties": false, "properties": { "bindings": { "items": { "$ref": "#/components/schemas/ProductLicensingBinding" }, "type": "array" }, "connections": { "items": { "$ref": "#/components/schemas/ExternalConnection" }, "type": "array" }, "default_provider": { "description": "The single active licensing provider for all products and both environments.", "enum": [ "licentivo", "custom_http" ], "type": "string" }, "mappings": { "items": { "$ref": "#/components/schemas/ExternalMapping" }, "type": "array" } }, "required": [ "connections", "bindings", "mappings", "default_provider" ], "type": "object" }, "LicensingConnectionsResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingConnections" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "LicensingProviderInput": { "additionalProperties": false, "properties": { "provider": { "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "provider" ], "type": "object" }, "LicensingSaved": { "additionalProperties": false, "properties": { "saved": { "const": true, "type": "boolean" } }, "required": [ "saved" ], "type": "object" }, "LicensingSavedResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/LicensingSaved" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" }, "LicentivoConnectionInput": { "additionalProperties": false, "properties": { "api_key": { "description": "Required for the first connection. Omit or leave empty to retain the saved server-side key.", "type": "string", "writeOnly": true }, "webhook_secret": { "description": "Optional secret of 32–256 bytes. Omit or leave empty to retain the saved secret.", "type": "string", "writeOnly": true } }, "type": "object" }, "Order": { "properties": { "action": { "type": "string" }, "amount_minor": { "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "id": { "format": "uuid", "type": "string" }, "paid_at": { "format": "date-time", "type": [ "string", "null" ] }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer" }, "plan_version_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "product_name": { "type": "string" }, "product_slug": { "type": "string" }, "purchase_periods": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "product_id", "product_name", "product_slug", "plan_version_id", "plan_name", "plan_version", "action", "status", "currency", "amount_minor", "purchase_periods", "created_at", "paid_at", "environment" ], "type": "object" }, "ProductLicensingBinding": { "additionalProperties": false, "properties": { "connection_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ] }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "product_id", "environment", "provider", "connection_id" ], "type": "object" }, "ProductLicensingInput": { "additionalProperties": false, "properties": { "connection_id": { "description": "External connection UUID; required for custom_http.", "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "mappings": { "items": { "$ref": "#/components/schemas/ExternalMappingInput" }, "type": "array" }, "provider": { "description": "Must match the instance-wide active licensing provider. Configure it with PUT /api/v1/admin/licensing/provider first.", "enum": [ "licentivo", "custom_http" ], "type": "string" } }, "required": [ "provider", "environment" ], "type": "object" }, "PublicLaunchConfig": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "launch_product_id": { "format": "uuid", "type": "string" }, "licentivo_product_id": { "format": "uuid", "type": "string" }, "merchant_origin": { "format": "uri", "type": "string" }, "schema_version": { "const": 1, "type": "integer" } }, "required": [ "schema_version", "merchant_origin", "launch_product_id", "licentivo_product_id", "environment" ], "type": "object" }, "PublicProductConfig": { "additionalProperties": false, "description": "Sanitized public configuration. Signature key provenance must be verified by the merchant.", "properties": { "app_version": { "type": "string" }, "base_url": { "format": "uri", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "maxProperties": 32, "minProperties": 1, "propertyNames": { "description": "Key identifiers are 1–128 UTF-8 bytes.", "minLength": 1, "type": "string", "x-maxBytes": 128 }, "type": "object" } }, "required": [ "product_id", "trusted_keys", "base_url" ], "type": "object" }, "PublicProductImport": { "additionalProperties": false, "description": "Launch public product configuration, populated from the official product ID and signing public keys. Legacy JSON with empty license_key/cache_path and false allow_http is accepted and stripped. Populated secrets and unknown fields are rejected.", "properties": { "allow_http": { "const": false }, "app_version": { "description": "At most 80 UTF-8 bytes.", "type": "string", "x-maxBytes": 80 }, "base_url": { "format": "uri", "type": "string" }, "cache_path": { "const": "" }, "device_name": { "maxLength": 128, "type": "string" }, "license_key": { "const": "" }, "product_id": { "format": "uuid", "type": "string" }, "trusted_keys": { "additionalProperties": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "maxProperties": 32, "minProperties": 1, "propertyNames": { "description": "Key identifiers are 1–128 UTF-8 bytes.", "minLength": 1, "type": "string", "x-maxBytes": 128 }, "type": "object" } }, "required": [ "product_id", "trusted_keys" ], "type": "object" }, "ReadinessResponse": { "properties": { "data": { "properties": { "code": { "enum": [ "DATABASE_NOT_CONFIGURED", "DATABASE_UNAVAILABLE", "DATABASE_SCHEMA_NOT_READY" ] }, "status": { "enum": [ "ready", "not_ready" ] } }, "required": [ "status" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" }, "RequestID": { "description": "Also returned in the X-Request-ID response header", "pattern": "^[a-f0-9]{32}$", "type": "string" }, "SessionGrant": { "properties": { "access_token": { "description": "Only returned for desktop login. Treat as secret; never put in URLs or logs.", "type": "string", "x-sensitive": true }, "expires_at": { "format": "date-time", "type": "string" }, "kind": { "enum": [ "website", "desktop" ], "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user", "kind", "expires_at" ], "type": "object" }, "SessionView": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "current": { "type": "boolean" }, "expires_at": { "format": "date-time", "type": "string" }, "id": { "format": "uuid", "type": "string" }, "kind": { "enum": [ "website", "desktop" ], "type": "string" } }, "required": [ "id", "kind", "created_at", "expires_at", "current" ], "type": "object" }, "User": { "properties": { "email": { "format": "email", "type": "string" }, "full_access": { "type": "boolean" }, "id": { "format": "uuid", "type": "string" }, "password_change_required": { "type": "boolean" }, "role": { "enum": [ "customer", "admin", "operations", "support" ], "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "id", "email", "verified", "role", "full_access", "password_change_required" ], "type": "object" } }, "securitySchemes": { "desktopBearer": { "description": "Opaque desktop session from auth/login with kind=desktop.", "scheme": "bearer", "type": "http" }, "websiteCookie": { "description": "Browser session. Mutations also require matching Origin and X-CSRF-Token from launch_csrf.", "in": "cookie", "name": "launch_session", "type": "apiKey" } } }, "info": { "description": "System, account, desktop licensing, integration wizard and basic purchase APIs. This is not the full staff administration/payment-webhook API. Runtime access must still pass the official Licentivo SDK. Email verification is required only when enabled by the merchant. Custom licensing connections and customer delivery are also documented. External receiver endpoints are specified separately in external-licensing-openapi.json.", "license": { "identifier": "MIT", "name": "MIT" }, "title": "Licentivo Launch Integration API", "version": "0.3.4-beta", "x-document-language": "en" }, "openapi": "3.1.0", "paths": { "/api/v1/admin/connections/licentivo": { "post": { "operationId": "configureLicentivoConnection", "parameters": [ { "in": "header", "name": "X-CSRF-Token", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicentivoConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": true, "description": "Connection identity, verified capabilities and catalog. Saved secrets are never returned.", "type": "object" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "websiteCookie": [] } ], "summary": "Validate and save the server-side Licentivo management connection", "tags": [ "Licentivo connection" ] } }, "/api/v1/admin/identity-notifications/{id}/retry": { "post": { "operationId": "retryIdentityNotification", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "reason": { "maxLength": 500, "minLength": 2, "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The original notice is scheduled for retry" }, "403": { "description": "Admin privileges required" }, "409": { "description": "Notice completed or being processed" } }, "security": [ { "websiteCookie": [] } ], "summary": "Retry account security revocation notice (admin)" } }, "/api/v1/admin/integration/check": { "post": { "description": "Requires the admin role. Website callers must supply Origin and X-CSRF-Token. ready=false reports incomplete configuration; no secret fields are returned. licentivo_product_id may be empty in an incomplete report.", "operationId": "checkApplicationIntegration", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "language": { "enum": [ "go", "python", "csharp", "java", "javascript", "rust", "ruby", "c", "cpp", "web" ], "type": "string" }, "product_id": { "format": "uuid", "type": "string" } }, "required": [ "product_id", "environment", "language" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/IntegrationBundle" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Automatically read the selected software mapping and signing public keys for direct SDK initialization", "tags": [ "Application integration" ] } }, "/api/v1/admin/integration/context": { "get": { "description": "Requires the admin role. Website callers must supply Origin and X-CSRF-Token. ready=false reports incomplete configuration; no secret fields are returned. licentivo_product_id may be empty in an incomplete report.", "operationId": "getIntegrationContext", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "additionalProperties": false, "properties": { "licensing_origin": { "type": "string" }, "merchant_origin": { "type": "string" } }, "required": [ "merchant_origin", "licensing_origin" ], "type": "object" }, "request_id": { "type": "string" } }, "required": [ "data" ], "type": "object" } } }, "description": "Public deployment context; no private startup settings" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Read the configured merchant origin and fixed licensing origin", "tags": [ "Application integration" ] } }, "/api/v1/admin/licensing/connections": { "get": { "operationId": "listLicensingChoices", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingConnectionsResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "List external connections, product bindings and mappings; Licentivo settings retain their existing API", "tags": [ "Custom licensing" ] }, "post": { "operationId": "createExternalLicensingConnection", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Verify and save a custom HTTP licensing connection", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/connections/{id}": { "put": { "operationId": "updateExternalLicensingConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Edit metadata/signing keys; destination, environment and network policy are immutable", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/connections/{id}/check": { "post": { "operationId": "checkExternalLicensingConnection", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalConnectionResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Refresh capabilities; last_check_error distinguishes a failed check in the 200 response", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/licensing/provider": { "put": { "operationId": "selectLicensingProvider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingProviderInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingSavedResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Enable one licensing provider for the entire instance; switching requires migration when other-provider orders exist", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/products/{id}/licensing": { "put": { "operationId": "configureProductLicensing", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductLicensingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicensingSavedResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Configure product connection and plan mappings for an environment using the active licensing provider", "tags": [ "Custom licensing" ] } }, "/api/v1/admin/refunds/{id}/reconcile": { "post": { "description": "Admin checks the original refund and restores the same operation after verifying the original transaction, amount, and currency from the channel receipt. If there is no receipt, only retry the original idempotent request within 23 hours of the original approval time on Stripe/PayPal; beyond this period, the original channel refund number is required. The operation is recorded in the audit, and no new refund operation number is created.", "operationId": "reconcileRefund", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "external_refund_id": { "maxLength": 128, "type": "string" }, "reason": { "maxLength": 500, "minLength": 2, "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Original task has been re-queued" }, "403": { "description": "Admin privileges and valid CSRF credentials required" }, "409": { "description": "Status conflict, receipt mismatch, or original channel refund number required" }, "503": { "description": "Original channel query temporarily unavailable" } }, "security": [ { "websiteCookie": [] } ], "summary": "Check and restore the original refund task" } }, "/api/v1/auth/complete-email": { "post": { "operationId": "completeAccountEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "password": { "type": "string", "writeOnly": true }, "token": { "type": "string", "writeOnly": true } }, "required": [ "token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [], "summary": "Complete a one-time email credential", "tags": [ "Application integration" ] } }, "/api/v1/auth/email": { "post": { "operationId": "requestAccountEmail", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "kind": { "enum": [ "verify", "reset" ], "type": "string" } }, "required": [ "email", "kind" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [], "summary": "Request a verification or password recovery email", "tags": [ "Application integration" ] } }, "/api/v1/auth/identity-keys": { "get": { "operationId": "launchIdentityPublicKeys", "responses": { "200": { "description": "Ed25519 public keys; never private signing material" } }, "summary": "Public pinned signing keys for Launch account identity" } }, "/api/v1/auth/login": { "post": { "description": "Set kind=desktop for applications and omit the browser Origin header. Website login sets cookies and omits access_token.", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "kind": { "default": "website", "enum": [ "desktop", "website" ], "type": "string" }, "password": { "type": "string", "writeOnly": true } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/SessionGrant" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [], "summary": "Sign in to website or desktop", "tags": [ "Application integration" ] } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Revoke the current session; SDK close, local cleanup and device release remain distinct actions", "tags": [ "Application integration" ] } }, "/api/v1/auth/register": { "post": { "operationId": "registerCustomer", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "password": { "description": "12–128 UTF-8 bytes (the server counts bytes, not Unicode characters).", "type": "string", "writeOnly": true, "x-maxBytes": 128, "x-minBytes": 12 } }, "required": [ "email", "password" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "accepted": { "type": "boolean" } }, "required": [ "accepted" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [], "summary": "Register a customer; verification follows merchant email settings", "tags": [ "Application integration" ] } }, "/api/v1/licensing/documentation": { "get": { "operationId": "readExternalLicensingGuide", "responses": { "200": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Public document" } }, "security": [], "summary": "Public external licensing documentation" } }, "/api/v1/licensing/protocol": { "get": { "operationId": "readExternalLicensingProtocol", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "Public document" } }, "security": [], "summary": "Public external licensing documentation" } }, "/api/v1/me": { "get": { "operationId": "currentUser", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "session_id": { "format": "uuid", "type": "string" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user", "session_id" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Read the authenticated account", "tags": [ "Application integration" ] } }, "/api/v1/me/orders": { "get": { "operationId": "listOrders", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Order" }, "type": "array" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "List the current customer’s orders", "tags": [ "Application integration" ] } }, "/api/v1/me/products/{id}/delivery": { "get": { "operationId": "readOwnedExternalDelivery", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "environment", "required": true, "schema": { "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalDeliveryResponse" } } }, "description": "Successful response" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid configuration/input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Administrator required, invalid CSRF, or forbidden scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "No owned resource" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Immutable mapping, migration required or purchase not ready" }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Rate limited" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Storage/external service unavailable" } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Read current owned external delivery; never a runtime authorization decision", "tags": [ "Custom licensing" ] } }, "/api/v1/me/sessions": { "get": { "operationId": "listSessions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SessionView" }, "type": "array" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "List active account sessions", "tags": [ "Application integration" ] } }, "/api/v1/me/sessions/{id}": { "delete": { "operationId": "revokeSession", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "completed": { "type": "boolean" } }, "required": [ "completed" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Revoke an owned session", "tags": [ "Application integration" ] } }, "/api/v1/orders": { "post": { "description": "Prices are calculated on the server. Renewal and upgrade require a server-issued quote. Follow the hosted checkout; redirect return is not proof of payment.", "operationId": "createCheckout", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "action": { "enum": [ "purchase", "renew", "upgrade" ], "type": "string" }, "environment": { "enum": [ "sandbox", "live" ], "type": "string" }, "idempotency_key": { "description": "Stable operation identifier, 16–80 UTF-8 bytes. Reuse the same key for retries of the same operation.", "type": "string", "x-maxBytes": 80, "x-minBytes": 16 }, "plan_version_id": { "format": "uuid", "type": "string" }, "product_id": { "format": "uuid", "type": "string" }, "provider": { "enum": [ "stripe", "paypal", "waffo", "paddle" ], "type": "string" }, "purchase_periods": { "minimum": 1, "type": "integer" }, "quote_token": { "type": "string", "writeOnly": true } }, "required": [ "product_id", "plan_version_id", "environment", "provider", "idempotency_key" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Create or recover an owned checkout using a stable idempotency key", "tags": [ "Application integration" ] } }, "/api/v1/orders/{id}": { "get": { "operationId": "getOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Read an owned order and fulfillment progress", "tags": [ "Application integration" ] } }, "/api/v1/orders/{id}/reconcile": { "post": { "operationId": "reconcileOrder", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/Checkout" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] }, { "websiteCookie": [] } ], "summary": "Query the payment provider for an owned order", "tags": [ "Application integration" ] } }, "/api/v1/software/products/{id}/credential": { "post": { "deprecated": true, "description": "Browser sessions cannot retrieve license keys. No client-selected user ID is accepted. 403 ENTITLEMENT_PENDING includes Retry-After: 3; retries must be bounded. EXPIRED/SUSPENDED require user action. 404 ENTITLEMENT_NOT_PURCHASED means no owned entitlement.", "operationId": "softwareCredential", "parameters": [ { "description": "Launch product ID, not the Licentivo product ID.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "environment" ], "type": "object" } } }, "required": true }, "responses": { "410": { "description": "LICENSE_CREDENTIAL_REMOVED; no license key is returned" } }, "security": [ { "desktopBearer": [] } ], "summary": "Removed: account SDKs must use identity exchange", "tags": [ "Application integration" ] } }, "/api/v1/software/products/{id}/identity": { "post": { "operationId": "exchangeAccountIdentity", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "environment": { "enum": [ "sandbox", "live" ], "type": "string" } }, "required": [ "environment" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/LaunchIdentity" } }, "type": "object" } } }, "description": "Identity context only. Licentivo decides authorization." }, "401": { "description": "Account session rejected" }, "503": { "description": "Identity connection unavailable" } }, "security": [ { "desktopBearer": [] } ], "summary": "Get a short-lived account identity assertion for the official SDK" } }, "/api/v1/software/products/{id}/status": { "get": { "description": "This is purchase/synchronization information, not a runtime authorization grant.", "operationId": "softwareStatus", "parameters": [ { "description": "Launch product ID, not the Licentivo product ID.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } }, { "in": "query", "name": "environment", "required": false, "schema": { "default": "live", "enum": [ "sandbox", "live" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/EntitlementStatus" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Successful response." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid fields, product ID or environment." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "LOGIN_FAILED (login) or AUTH_REQUIRED (expired/revoked session). Clear rejected sessions; never fall back after an explicit denial." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Forbidden, email verification required, initial password change required or explicit entitlement denial." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "RATE_LIMITED; do not retry in a tight loop.", "headers": { "Retry-After": { "description": "Seconds to wait before another attempt. Respect this value and bound total retries.", "schema": { "minimum": 0, "type": "integer" } } } }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Temporary service or database failure. Offline access is permitted only by a valid official SDK signed grant." } }, "security": [ { "desktopBearer": [] } ], "summary": "Read actionable status for the authenticated customer and requested product", "tags": [ "Application integration" ] } }, "/api/v1/system/status": { "get": { "operationId": "getSystemStatus", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "implemented": { "items": { "type": "string" }, "type": "array" }, "phase": { "const": "local-development" }, "product": { "const": "Licentivo Launch" }, "sales_enabled": { "const": false }, "version": { "type": "string" } }, "required": [ "product", "version", "phase", "sales_enabled", "implemented" ], "type": "object" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "data", "request_id" ], "type": "object" } } }, "description": "Current development phase and implementation scope" } }, "summary": "Expose version and implementation scope without configuration or credentials" } }, "/healthz": { "get": { "operationId": "getLiveness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } }, "description": "The HTTP process is running" } }, "summary": "Process liveness, independent of database readiness" } }, "/readyz": { "get": { "operationId": "getReadiness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "The database is ready; this does not certify payment or licensing acceptance" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } }, "description": "The database is unconfigured, unavailable, or missing required tables" } }, "summary": "Check MySQL connectivity and required GORM tables" } } }, "servers": [ { "description": "Replace with your merchant origin; HTTP is permitted only for loopback sandbox development.", "url": "https://shop.example.com" } ] }