{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "KDPika Licensing API", "version": "v1", "description": "Source-validated licensing contract. This is not a payment API for developers software buyers. Use Sandbox for testing; documented SDK/idempotency limitations remain unchanged.", "contact": { "name": "KDPika support", "url": "https://licensing.kdpika.com/security", "email": "hi@kdpika.com" } }, "servers": [ { "url": "https://licensing.kdpika.com/api/v1", "description": "Managed API; environment is credential/header-bound, not a different host." } ], "tags": [ { "name": "Keys", "description": "Public Ed25519 trust material." }, { "name": "Licenses", "description": "Installation licensing and scoped server-side management." } ], "paths": { "/public-key": { "get": { "operationId": "publicKey", "summary": "Retrieve the current public verification key.", "description": "Retrieve the current public verification key. Use the correct installation/environment and verify signed state before granting access.", "tags": [ "Keys" ], "security": [], "parameters": [], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } }, "Cache-Control": { "description": "public, max-age=3600.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyResponse" }, "example": { "success": true, "key": { "algorithm": "Ed25519", "key_id": "ed25519_2b9bc7e214b1209f", "public_key": "3VNX3t2NIvzg37o1w-bjxJdJVFtgbfpR-_Q80u4U5tQ", "encoding": "base64url" }, "request_id": "req_d9e278f6722a692a5dc3bbe8" } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_33cd6936824bce67ae013911" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } } }, "x-required-scope": null, "x-errors": [ "RATE_LIMITED", "INTERNAL_ERROR" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::publicKey" } }, "/licenses": { "post": { "operationId": "create", "summary": "Issue a license after your backend verifies the buyer purchase.", "description": "Issue a license after your backend verifies the buyer purchase. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable organization-scoped business-event key,8–190 trimmed characters; retention24hours, known expiry/concurrency limits.", "schema": { "type": "string", "minLength": 8, "maxLength": 190 } } ], "responses": { "201": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } }, "Idempotent-Replay": { "description": "true only when returning a stored create response.", "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "license_key": "YOUR_NEW_LICENSE_KEY", "expires_at": "2026-11-16T10:39:35+00:00", "environment": "sandbox" }, "request_id": "req_1c0f804fd7c455f25fa1f791" } } } }, "422": { "description": "INVALID_REQUEST: Input constraints or entitlement/resource/renewal domain rejection", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST" ] } } } } } ] }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "A valid Idempotency-Key header is required." }, "request_id": "req_003bfc05e13e96c496b5cd69" } } } } } }, "404": { "description": "PLAN_NOT_FOUND: Create product/plan does not resolve within active API-key product", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "PLAN_NOT_FOUND" ] } } } } } ] }, "examples": { "PLAN_NOT_FOUND": { "summary": "PLAN_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "PLAN_NOT_FOUND", "message": "The product or plan is not available to this API key." }, "request_id": "req_7c32fac8c57a426112bb09db" } } } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT: Organization key reused with different decoded-body hash (member order matters)", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "IDEMPOTENCY_CONFLICT" ] } } } } } ] }, "examples": { "IDEMPOTENCY_CONFLICT": { "summary": "IDEMPOTENCY_CONFLICT", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "IDEMPOTENCY_CONFLICT", "message": "This idempotency key was already used with a different request." }, "request_id": "req_81cea3692118c9535bfd4b24" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_0cc5e09b7e2e6268ba080ccc" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_c6b37ab29c8392bb94adaf9e" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_02465737f6708774221ff4e5" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_45753958be2052e108c5fa03" } } } } } } }, "x-required-scope": "licenses:write", "x-errors": [ "INVALID_REQUEST", "PLAN_NOT_FOUND", "IDEMPOTENCY_CONFLICT", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::create", "requestBody": { "description": "Recommended JSON input. Backend casts strings and ignores unknown fields.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRequest" }, "example": { "product_id": "YOUR_INTERNAL_PRODUCT_ID", "plan_id": "YOUR_PRODUCT_PLAN_ID", "customer": { "email": "customer@example.invalid", "name": "Example customer", "company": "Example company", "external_id": "YOUR_CUSTOMER_REFERENCE" } } } } } } }, "/licenses/activate": { "post": { "operationId": "activate", "summary": "Bind a customer license to one persisted installation.", "description": "Bind a customer license to one persisted installation. Use the correct installation/environment and verify signed state before granting access.", "tags": [ "Licenses" ], "security": [ { "PublicAppId": [] } ], "parameters": [ { "name": "X-App-ID", "in": "header", "required": true, "description": "Public App ID,8–80 trimmed characters.", "schema": { "type": "string", "minLength": 8, "maxLength": 80 } }, { "name": "X-Environment", "in": "header", "required": false, "description": "Activation environment; backend normalizes case. Does not override token/developer-key bindings.", "schema": { "type": "string", "enum": [ "SANDBOX", "LIVE" ], "default": "SANDBOX" } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateResponse" }, "example": { "success": true, "activation_token": "YOUR_ACTIVATION_TOKEN", "license": { "payload": { "license_id": "lic_578581bd80c2a672da30fc29", "product_id": "app_a642cd24641ec976626b", "product": "Docs fixture product", "plan": "fixture-plan", "status": "active", "environment": "sandbox", "expires_at": "2026-11-16T10:39:35+00:00", "license_key_mask": "TESTDOCS-••••-••••-HAHH", "starts_at": "2026-10-17T10:39:35+00:00", "created_at": "2026-10-17T12:39:35+00:00", "max_devices": 2, "max_activations": 4, "activation_count": 1, "min_version": null, "max_version": null, "active_devices": 1, "customer": { "id": "cus_d7db5516f8377f89a869e293", "name": "Synthetic contract customer", "email": "contract-6b9f0843f1d3609f@example.invalid", "company": null, "country": null }, "product_details": { "id": "app_a642cd24641ec976626b", "name": "Docs fixture product", "platform": "desktop" }, "plan_details": { "id": "plan_3bf54c099326639ee183661f", "name": "Fixture plan", "slug": "fixture-plan", "billing_type": "monthly", "price": 19.5, "currency": "EUR", "duration_days": 30, "trial_days": null }, "features": { "pdf_export": true }, "device": { "id": "dev_299a6753c013047b3ed013de", "installation_hash": "e119b615ebfb5e5a2da5ea9c2a64b2117621399ff61d16718d460e0bb919a988", "name": "Synthetic local installation", "platform": "test", "app_version": "1.0.0" }, "server_time": "2026-10-17T10:39:35+00:00", "next_validation_at": "2026-10-18T10:39:35+00:00", "offline_grace_until": "2026-10-24T10:39:35+00:00" }, "signature": "wYwFAPoyaaIVtq8zvUHlQeyqV91sI7115WJHUzY7unDEjOts7MrN_OL3PZAd-Ahd-OdfI-EjIwAVwhfLbYQlDQ", "algorithm": "Ed25519", "key_id": "ed25519_2b9bc7e214b1209f" }, "request_id": "req_11a6f2cf9cfffdaf92e1a6ce" } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many activation attempts. Try again later." }, "request_id": "req_32e142a10bf926e140a29268" } } } } } }, "422": { "description": "INVALID_REQUEST: Input constraints or entitlement/resource/renewal domain rejection", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST" ] } } } } } ] }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "The activation request is incomplete." }, "request_id": "req_683fdb9cc07c235ee0bf7534" } } } } } }, "404": { "description": "INVALID_LICENSE: Activation key/product/environment/customer email mismatch; SDK empty key local error has no HTTP", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_LICENSE" ] } } } } } ] }, "examples": { "INVALID_LICENSE": { "summary": "INVALID_LICENSE", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_LICENSE", "message": "The license could not be activated." }, "request_id": "req_8151af7bb248a097273eacaf" } } } } } }, "403": { "description": "LICENSE_EXPIRED: Elapsed expires_at before state check; or EXPIRED state; SDK local expiry has no HTTP; LICENSE_REVOKED: License REVOKED and no elapsed deadline taking precedence; LICENSE_SUSPENDED: License SUSPENDED and no elapsed deadline taking precedence; LICENSE_CANCELLED: License CANCELLED and no elapsed deadline taking precedence; LICENSE_PENDING: License PENDING and no elapsed deadline taking precedence; APP_VERSION_NOT_SUPPORTED: Nonempty activation app_version outside configured range", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_EXPIRED", "LICENSE_REVOKED", "LICENSE_SUSPENDED", "LICENSE_CANCELLED", "LICENSE_PENDING", "APP_VERSION_NOT_SUPPORTED" ] } } } } } ] }, "examples": { "LICENSE_EXPIRED": { "summary": "LICENSE_EXPIRED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_EXPIRED", "message": "This license is not active." }, "request_id": "req_509edfc81c0aa4bf592304a5" } }, "LICENSE_REVOKED": { "summary": "LICENSE_REVOKED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_REVOKED", "message": "This license is not active." }, "request_id": "req_e1cd9d03bd77dfe24f4912aa" } }, "LICENSE_SUSPENDED": { "summary": "LICENSE_SUSPENDED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_SUSPENDED", "message": "This license is not active." }, "request_id": "req_a9437e9d55b38eac8cd8272b" } }, "LICENSE_CANCELLED": { "summary": "LICENSE_CANCELLED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_CANCELLED", "message": "This license is not active." }, "request_id": "req_11adfde7c34172a8480cbbf7" } }, "LICENSE_PENDING": { "summary": "LICENSE_PENDING", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_PENDING", "message": "This license is not active." }, "request_id": "req_3ebeb7947ac81be0ca837eab" } }, "APP_VERSION_NOT_SUPPORTED": { "summary": "APP_VERSION_NOT_SUPPORTED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "APP_VERSION_NOT_SUPPORTED", "message": "This application version is not licensed." }, "request_id": "req_ce100865eaecf80eae13afeb" } } } } } }, "409": { "description": "DEVICE_LIMIT_REACHED: New/inactive installation while active seats >= license.max_devices; ACTIVATION_LIMIT_REACHED: New/inactive installation while activation_count >= max_activations", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DEVICE_LIMIT_REACHED", "ACTIVATION_LIMIT_REACHED" ] } } } } } ] }, "examples": { "DEVICE_LIMIT_REACHED": { "summary": "DEVICE_LIMIT_REACHED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "DEVICE_LIMIT_REACHED", "message": "This license cannot activate another device." }, "request_id": "req_5bac2e038670c3987ae9d0a5" } }, "ACTIVATION_LIMIT_REACHED": { "summary": "ACTIVATION_LIMIT_REACHED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "ACTIVATION_LIMIT_REACHED", "message": "This license has reached its activation limit." }, "request_id": "req_f986dae819120ce9a097e54a" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } } }, "x-required-scope": null, "x-errors": [ "RATE_LIMITED", "INVALID_REQUEST", "INVALID_LICENSE", "LICENSE_EXPIRED", "LICENSE_REVOKED", "LICENSE_SUSPENDED", "LICENSE_CANCELLED", "LICENSE_PENDING", "APP_VERSION_NOT_SUPPORTED", "DEVICE_LIMIT_REACHED", "ACTIVATION_LIMIT_REACHED", "INTERNAL_ERROR" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::activate", "requestBody": { "description": "Recommended activation JSON. Strings are trimmed by the backend.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateRequest" }, "example": { "license_key": "YOUR_CUSTOMER_LICENSE_KEY", "device_id": "YOUR_PERSISTED_INSTALLATION_ID", "email": "customer@example.invalid", "device_name": "Example workstation", "platform": "macOS", "app_version": "1.0.0" } } } } } }, "/licenses/validate": { "post": { "operationId": "validate", "summary": "Refresh the signed state of an activated installation.", "description": "Refresh the signed state of an activated installation. Use the correct installation/environment and verify signed state before granting access.", "tags": [ "Licenses" ], "security": [ { "ActivationToken": [] } ], "parameters": [ { "name": "X-Installation-ID", "in": "header", "required": false, "description": "Always send the persisted ID. Omission signs a null installation hash that official clients reject.", "schema": { "type": "string", "minLength": 16, "maxLength": 255 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" }, "example": { "success": true, "valid": true, "license": { "payload": { "license_id": "lic_578581bd80c2a672da30fc29", "product_id": "app_a642cd24641ec976626b", "product": "Docs fixture product", "plan": "fixture-plan", "status": "active", "environment": "sandbox", "expires_at": "2026-11-16T10:39:35+00:00", "license_key_mask": "TESTDOCS-••••-••••-HAHH", "starts_at": "2026-10-17T10:39:35+00:00", "created_at": "2026-10-17T12:39:35+00:00", "max_devices": 2, "max_activations": 4, "activation_count": 1, "min_version": null, "max_version": null, "active_devices": 1, "customer": { "id": "cus_d7db5516f8377f89a869e293", "name": "Synthetic contract customer", "email": "contract-6b9f0843f1d3609f@example.invalid", "company": null, "country": null }, "product_details": { "id": "app_a642cd24641ec976626b", "name": "Docs fixture product", "platform": "desktop" }, "plan_details": { "id": "plan_3bf54c099326639ee183661f", "name": "Fixture plan", "slug": "fixture-plan", "billing_type": "monthly", "price": 19.5, "currency": "EUR", "duration_days": 30, "trial_days": null }, "features": { "pdf_export": true }, "device": { "id": "dev_299a6753c013047b3ed013de", "installation_hash": "e119b615ebfb5e5a2da5ea9c2a64b2117621399ff61d16718d460e0bb919a988", "name": "Synthetic local installation", "platform": "test", "app_version": "1.0.0" }, "server_time": "2026-10-17T10:39:35+00:00", "next_validation_at": "2026-10-18T10:39:35+00:00", "offline_grace_until": "2026-10-24T10:39:35+00:00" }, "signature": "wYwFAPoyaaIVtq8zvUHlQeyqV91sI7115WJHUzY7unDEjOts7MrN_OL3PZAd-Ahd-OdfI-EjIwAVwhfLbYQlDQ", "algorithm": "Ed25519", "key_id": "ed25519_2b9bc7e214b1209f" }, "request_id": "req_b8b3d83f5a1820e7c2f16167" } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many validation requests. Try again later." }, "request_id": "req_d6ddc1161550f60c0d78f34c" } } } } } }, "401": { "description": "INVALID_TOKEN: Missing/non-act_/unknown/revoked/deactivated activation token", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_TOKEN" ] } } } } } ] }, "examples": { "INVALID_TOKEN": { "summary": "INVALID_TOKEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_TOKEN", "message": "The activation token is invalid." }, "request_id": "req_968544052d9c084e1fe82941" } } } } } }, "422": { "description": "INVALID_REQUEST: Input constraints or entitlement/resource/renewal domain rejection", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST" ] } } } } } ] }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "The installation identifier is invalid." }, "request_id": "req_471906d9cf79893df3f8bc9e" } } } } } }, "403": { "description": "DEVICE_NOT_AUTHORIZED: Token is active but associated device is not ACTIVE; DEVICE_MISMATCH: Provided installation ID does not match token-bound HMAC hash; LICENSE_EXPIRED: Elapsed expires_at before state check; or EXPIRED state; SDK local expiry has no HTTP; LICENSE_REVOKED: License REVOKED and no elapsed deadline taking precedence; LICENSE_SUSPENDED: License SUSPENDED and no elapsed deadline taking precedence; LICENSE_CANCELLED: License CANCELLED and no elapsed deadline taking precedence; LICENSE_PENDING: License PENDING and no elapsed deadline taking precedence", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "DEVICE_NOT_AUTHORIZED", "DEVICE_MISMATCH", "LICENSE_EXPIRED", "LICENSE_REVOKED", "LICENSE_SUSPENDED", "LICENSE_CANCELLED", "LICENSE_PENDING" ] } } } } } ] }, "examples": { "DEVICE_NOT_AUTHORIZED": { "summary": "DEVICE_NOT_AUTHORIZED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "DEVICE_NOT_AUTHORIZED", "message": "This device is not authorized." }, "request_id": "req_b095e1a258c292121dd0b4ef" } }, "DEVICE_MISMATCH": { "summary": "DEVICE_MISMATCH", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "DEVICE_MISMATCH", "message": "The activation token belongs to another installation." }, "request_id": "req_7a0d2126c9138467e9e97ab9" } }, "LICENSE_EXPIRED": { "summary": "LICENSE_EXPIRED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_EXPIRED", "message": "This license is not active." }, "request_id": "req_473ea0a6a6a0ee3b6a6e5b09" } }, "LICENSE_REVOKED": { "summary": "LICENSE_REVOKED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_REVOKED", "message": "This license is not active." }, "request_id": "req_c720588de2ec0491adb9d545" } }, "LICENSE_SUSPENDED": { "summary": "LICENSE_SUSPENDED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_SUSPENDED", "message": "This license is not active." }, "request_id": "req_b1040cabf9d45d395ce8ba3a" } }, "LICENSE_CANCELLED": { "summary": "LICENSE_CANCELLED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_CANCELLED", "message": "This license is not active." }, "request_id": "req_a5baf6ae85bc05dd2cdef85f" } }, "LICENSE_PENDING": { "summary": "LICENSE_PENDING", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_PENDING", "message": "This license is not active." }, "request_id": "req_410ae3ba271488b05419943e" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } } }, "x-required-scope": null, "x-errors": [ "RATE_LIMITED", "INVALID_TOKEN", "INVALID_REQUEST", "DEVICE_NOT_AUTHORIZED", "DEVICE_MISMATCH", "LICENSE_EXPIRED", "LICENSE_REVOKED", "LICENSE_SUSPENDED", "LICENSE_CANCELLED", "LICENSE_PENDING", "INTERNAL_ERROR" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::validate", "requestBody": { "description": "No body fields consumed; omit the body or send{}.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" }, "example": {} } } } } }, "/licenses/deactivate": { "post": { "operationId": "deactivate", "summary": "Release this installation device seat.", "description": "Release this installation device seat. Use the correct installation/environment and verify signed state before granting access.", "tags": [ "Licenses" ], "security": [ { "ActivationToken": [] } ], "parameters": [], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeactivateResponse" }, "example": { "success": true, "deactivated": true, "request_id": "req_29039d899dd3655d7ada1c89" } } } }, "401": { "description": "INVALID_TOKEN: Missing/non-act_/unknown/revoked/deactivated activation token", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_TOKEN" ] } } } } } ] }, "examples": { "INVALID_TOKEN": { "summary": "INVALID_TOKEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_TOKEN", "message": "The activation token is invalid." }, "request_id": "req_68730901d939d41684b87d6d" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } } }, "x-required-scope": null, "x-errors": [ "INVALID_TOKEN", "INTERNAL_ERROR" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::deactivate", "requestBody": { "description": "No body fields consumed; omit the body or send{}.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" }, "example": {} } } } } }, "/licenses/{license}": { "get": { "operationId": "show", "summary": "Read a scoped unsigned license summary.", "description": "Read a scoped unsigned license summary. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "license_key_mask": "TESTDOCS-••••-••••-HAHH", "status": "active", "environment": "sandbox", "starts_at": "2026-10-17T10:39:35+00:00", "expires_at": "2026-11-16T10:39:35+00:00", "created_at": "2026-10-17T12:39:35+00:00", "updated_at": "2026-10-17T12:39:35+00:00", "max_devices": 2, "active_devices": 0, "max_activations": 4, "activation_count": 0, "min_version": null, "max_version": null, "revocation_reason": null, "product": { "id": "app_a642cd24641ec976626b", "name": "Docs fixture product" }, "plan": { "id": "plan_3bf54c099326639ee183661f", "name": "Fixture plan", "slug": "fixture-plan", "billing_type": "monthly", "price": 19.5, "currency": "EUR" }, "customer": { "id": "cus_d7db5516f8377f89a869e293", "name": "Synthetic contract customer", "email": "contract-6b9f0843f1d3609f@example.invalid", "company": null, "country": null } }, "request_id": "req_2e71dc11a311d6a5d34c50cb" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_32365cd5ddd30e1db4849eb8" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_93de42dcace6be89a65915ac" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_032e49a99c68369cba8952bb" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_18bde8deeebc91887f49e5cb" } } } } } } }, "x-required-scope": "licenses:read", "x-errors": [ "LICENSE_NOT_FOUND", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::show" } }, "/licenses/{license}/revoke": { "post": { "operationId": "revoke", "summary": "Revoke a license and its active tokens.", "description": "Revoke a license and its active tokens. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "status": "revoked" }, "request_id": "req_3a543bd6e559e7752e917105" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_a8ca7256664e1f11e2cdcc61" } } } } } }, "409": { "description": "INVALID_STATE: Forbidden state transition or restore with elapsed expiry", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_STATE" ] } } } } } ] }, "examples": { "INVALID_STATE": { "summary": "INVALID_STATE", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_STATE", "message": "This license status transition is not allowed." }, "request_id": "req_b26dc95d6e22badfc95d4a65" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_fa31d4af0f3d0f99bf44bfd5" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_5008edc3d5d78c3a8e221530" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_854c6b30962de989756665e3" } } } } } } }, "x-required-scope": "licenses:write", "x-errors": [ "LICENSE_NOT_FOUND", "INVALID_STATE", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::revoke", "requestBody": { "description": "Reason consumed for status actions; unknown fields ignored.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonRequest" }, "example": { "reason": "Customer support request" } } } } } }, "/licenses/{license}/suspend": { "post": { "operationId": "suspend", "summary": "Suspend an eligible license and invalidate its active tokens.", "description": "Suspend an eligible license and invalidate its active tokens. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "status": "suspended" }, "request_id": "req_793bbd0d0f1194351154241a" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_3cc70f4f2ddebef823658fbc" } } } } } }, "409": { "description": "INVALID_STATE: Forbidden state transition or restore with elapsed expiry", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_STATE" ] } } } } } ] }, "examples": { "INVALID_STATE": { "summary": "INVALID_STATE", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_STATE", "message": "This license status transition is not allowed." }, "request_id": "req_87f3dd361a452fa25bb78e35" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_93072b3bc8e7a599481dcee1" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_8a65269f4a55066d35786e35" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_b887d78cfe3bcc3c96355787" } } } } } } }, "x-required-scope": "licenses:write", "x-errors": [ "LICENSE_NOT_FOUND", "INVALID_STATE", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::suspend", "requestBody": { "description": "Reason consumed for status actions; unknown fields ignored.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonRequest" }, "example": { "reason": "Customer support request" } } } } } }, "/licenses/{license}/restore": { "post": { "operationId": "restore", "summary": "Restore an eligible license without reviving old tokens.", "description": "Restore an eligible license without reviving old tokens. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "status": "active" }, "request_id": "req_0dd8d2e77cf580ba8b5d491f" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_b598aff6d76664d25bfb87f4" } } } } } }, "409": { "description": "INVALID_STATE: Forbidden state transition or restore with elapsed expiry", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_STATE" ] } } } } } ] }, "examples": { "INVALID_STATE": { "summary": "INVALID_STATE", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_STATE", "message": "This license status transition is not allowed." }, "request_id": "req_41b1cc76471c1cf660f7a94b" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_1a4d0ca60f40bd2a679a64b7" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_f5855b8111ee8a85d926859b" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_a51e59ca9c6835a019ba1fba" } } } } } } }, "x-required-scope": "licenses:write", "x-errors": [ "LICENSE_NOT_FOUND", "INVALID_STATE", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::restore", "requestBody": { "description": "Reason consumed for status actions; unknown fields ignored.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReasonRequest" }, "example": { "reason": "Customer support request" } } } } } }, "/licenses/{license}/renew": { "post": { "operationId": "renew", "summary": "Extend license expiry without charging or changing its plan.", "description": "Extend license expiry without charging or changing its plan. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewResponse" }, "example": { "success": true, "license": { "id": "lic_578581bd80c2a672da30fc29", "status": "active", "expires_at": "2026-12-16T10:39:35+00:00" }, "request_id": "req_ef518703be07a281beed3534" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_8051f601b49b9d5b639b2e01" } } } } } }, "422": { "description": "INVALID_REQUEST: Input constraints or entitlement/resource/renewal domain rejection", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST" ] } } } } } ] }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "Renewal days must be between 1 and 3650." }, "request_id": "req_6302661e53fb98f83f100c33" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_49eec722d835e234f8b6b0bb" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_e40ce057a57f07b4dc4ae024" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_c2cf114ade63be0f12d2f933" } } } } } } }, "x-required-scope": "licenses:write", "x-errors": [ "LICENSE_NOT_FOUND", "INVALID_REQUEST", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::renew", "requestBody": { "description": "Recommended integer input; backend FILTER_VALIDATE_INT also accepts certain numeric strings.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenewRequest" }, "example": { "days": 30 } } } } } }, "/licenses/{license}/reset-devices": { "post": { "operationId": "resetDevices", "summary": "Release active devices and revoke their tokens.", "description": "Release active devices and revoke their tokens. Management credentials belong on your trusted backend.", "tags": [ "Licenses" ], "security": [ { "DeveloperKey": [] } ], "parameters": [ { "name": "license", "in": "path", "required": true, "description": "Opaque license identifier. Scoped lookup returns404; no UUID/length contract.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Successful operation.", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } }, "X-RateLimit-Remaining": { "description": "Remaining allowance in the reached endpoint bucket.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Bucket reset, Unix seconds. Error responses omit this header.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetResponse" }, "example": { "success": true, "devices_reset": true, "request_id": "req_94a800afce76076106be37b8" } } } }, "404": { "description": "LICENSE_NOT_FOUND: Management scoped license absent", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "LICENSE_NOT_FOUND" ] } } } } } ] }, "examples": { "LICENSE_NOT_FOUND": { "summary": "LICENSE_NOT_FOUND", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "LICENSE_NOT_FOUND", "message": "The license was not found." }, "request_id": "req_2b3cfe6926be77758df88733" } } } } } }, "422": { "description": "INVALID_REQUEST: Input constraints or entitlement/resource/renewal domain rejection", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST" ] } } } } } ] }, "examples": { "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_REQUEST", "message": "License not found." }, "request_id": "req_69a1452f45711af2b7f59952" } } } } } }, "500": { "description": "INTERNAL_ERROR: Uncaught exception at global boundary", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INTERNAL_ERROR" ] } } } } } ] }, "examples": { "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "description": "Real shared global error boundary capture.", "value": { "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Something went wrong." }, "request_id": "req_9ef7ad1a823b9d3a757fb532" } } } } } }, "401": { "description": "INVALID_API_KEY: Missing/invalid/revoked key or prohibited subscription/environment", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_API_KEY" ] } } } } } ] }, "examples": { "INVALID_API_KEY": { "summary": "INVALID_API_KEY", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "INVALID_API_KEY", "message": "The API key is invalid." }, "request_id": "req_77768624abea6cd383ddb4ce" } } } } } }, "403": { "description": "FORBIDDEN: Developer scope missing; checkout account role not OWNER/ADMIN", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "FORBIDDEN" ] } } } } } ] }, "examples": { "FORBIDDEN": { "summary": "FORBIDDEN", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "FORBIDDEN", "message": "This API key does not have the required scope." }, "request_id": "req_824aea868e2dd19c0151bb83" } } } } } }, "429": { "description": "RATE_LIMITED: Bucket exhausted; wait for window reset; no licensing Retry-After header", "headers": { "X-Request-ID": { "description": "Current request correlation ID; can differ from an idempotent replay body.", "schema": { "$ref": "#/components/schemas/RequestId" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "RATE_LIMITED" ] } } } } } ] }, "examples": { "RATE_LIMITED": { "summary": "RATE_LIMITED", "description": "Real isolated Sandbox response for this operation.", "value": { "success": false, "error": { "code": "RATE_LIMITED", "message": "Too many requests. Try again later." }, "request_id": "req_e6bf9af389d12d0c65a6713a" } } } } } } }, "x-required-scope": "devices:write", "x-errors": [ "LICENSE_NOT_FOUND", "INVALID_REQUEST", "INTERNAL_ERROR", "INVALID_API_KEY", "FORBIDDEN", "RATE_LIMITED" ], "x-source": "app/Controllers/Api/V1/PhaseTwoController.php::resetDevices", "requestBody": { "description": "No body fields consumed; omit the body or send{}.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyRequest" }, "example": {} } } } } } }, "components": { "securitySchemes": { "PublicAppId": { "type": "apiKey", "in": "header", "name": "X-App-ID", "description": "Public product identifier for activation; also requires customer license/device details." }, "ActivationToken": { "type": "http", "scheme": "bearer", "bearerFormat": "act_ installation token", "description": "Installation-scoped secret returned by activation." }, "DeveloperKey": { "type": "http", "scheme": "bearer", "bearerFormat": "lmp_ developer key", "description": "Scoped product/environment key; trusted backend only. Scope is documented in x-required-scope." } }, "schemas": { "RequestId": { "type": "string", "description": "Request correlation ID. Replay bodies can retain an earlier ID.", "pattern": "^req_[a-f0-9]{24}$" }, "PublicKey": { "type": "object", "description": "Current global verification key, not a historical key ring.", "properties": { "algorithm": { "type": "string", "description": "Fixed verification algorithm.", "const": "Ed25519" }, "key_id": { "type": "string", "description": "ed25519_ plus first16 hex SHA256 characters of raw public key.", "pattern": "^ed25519_[a-f0-9]{16}$" }, "public_key": { "type": "string", "description": "Unpadded base64url of32 raw Ed25519 public-key bytes.", "pattern": "^[A-Za-z0-9_-]{43}$" }, "encoding": { "type": "string", "description": "Raw-key encoding.", "const": "base64url" } }, "required": [ "algorithm", "key_id", "public_key", "encoding" ], "additionalProperties": false }, "Customer": { "type": "object", "description": "Customer information; personal data, not an authentication credential.", "properties": { "id": { "type": "string", "description": "Customer public identifier." }, "name": { "type": [ "string", "null" ], "description": "Optional customer name." }, "email": { "type": "string", "description": "Customer email associated with this license." }, "company": { "type": [ "string", "null" ], "description": "Optional company." }, "country": { "type": [ "string", "null" ], "description": "Optional country." } }, "required": [ "id", "name", "email", "company", "country" ], "additionalProperties": false }, "ProductDetails": { "type": "object", "description": "Product display metadata.", "properties": { "id": { "type": "string", "description": "Public App ID." }, "name": { "type": "string", "description": "Product display name." }, "platform": { "type": "string", "description": "Lowercase configured product platform." } }, "required": [ "id", "name", "platform" ], "additionalProperties": false }, "PlanDetails": { "type": "object", "description": "Product plan, not the developer platform subscription.", "properties": { "id": { "type": "string", "description": "Internal product-plan identifier." }, "name": { "type": "string", "description": "Plan display name." }, "slug": { "type": "string", "description": "Plan slug." }, "billing_type": { "type": "string", "description": "Lowercase product-plan billing type." }, "price": { "type": "number", "description": "PHP float; preserve numeric tokens such as19.0 for signatures." }, "currency": { "type": "string", "description": "Configured product-plan currency." }, "duration_days": { "type": [ "integer", "null" ], "description": "Configured duration in days." }, "trial_days": { "type": [ "integer", "null" ], "description": "Configured trial duration in days." } }, "required": [ "id", "name", "slug", "billing_type", "price", "currency", "duration_days", "trial_days" ], "additionalProperties": false }, "Device": { "type": "object", "description": "Installation binding and descriptions.", "properties": { "id": { "type": "string", "description": "Device public identifier." }, "installation_hash": { "type": [ "string", "null" ], "description": "SHA256 of supplied installation ID; null if validation header was omitted." }, "name": { "type": [ "string", "null" ], "description": "Optional device label; activation can return an empty string." }, "platform": { "type": [ "string", "null" ], "description": "Optional platform description." }, "app_version": { "type": [ "string", "null" ], "description": "Optional application version." } }, "required": [ "id", "installation_hash", "name", "platform", "app_version" ], "additionalProperties": false }, "Features": { "description": "Dynamic plan feature JSON values; empty PHP feature array may be[]. Validate types before use.", "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "array", "maxItems": 0, "items": {} } ] }, "LicensePayload": { "type": "object", "description": "Exact signed snapshot. Signature authenticity alone does not grant access.", "properties": { "license_id": { "type": "string", "description": "License public identifier." }, "product_id": { "type": "string", "description": "Public App ID; compare to configured product." }, "product": { "type": "string", "description": "Product display name." }, "plan": { "type": "string", "description": "Product-plan slug." }, "status": { "type": "string", "description": "Stored license status in lowercase.", "enum": [ "active", "suspended", "revoked", "expired", "pending", "cancelled" ] }, "environment": { "type": "string", "description": "Bound license environment.", "enum": [ "sandbox", "live" ] }, "expires_at": { "type": [ "string", "null" ], "description": "Independent license expiry; null has no configured expiry.", "format": "date-time" }, "license_key_mask": { "type": "string", "description": "Display-only masked key." }, "starts_at": { "type": [ "string", "null" ], "description": "Configured license start, currently not enforced by server eligibility.", "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp; database-timezone discrepancy is disclosed.", "format": "date-time" }, "max_devices": { "type": "integer", "description": "Concurrent device limit." }, "max_activations": { "type": [ "integer", "null" ], "description": "Cumulative activation cap; null means no configured cap." }, "activation_count": { "type": "integer", "description": "Cumulative consumed activations." }, "min_version": { "type": [ "string", "null" ], "description": "Optional lower version restriction." }, "max_version": { "type": [ "string", "null" ], "description": "Optional upper version restriction." }, "active_devices": { "type": "integer", "description": "Active count at snapshot time." }, "customer": { "$ref": "#/components/schemas/Customer" }, "product_details": { "$ref": "#/components/schemas/ProductDetails" }, "plan_details": { "$ref": "#/components/schemas/PlanDetails" }, "features": { "$ref": "#/components/schemas/Features" }, "device": { "$ref": "#/components/schemas/Device" }, "server_time": { "type": "string", "description": "Signed snapshot time in UTC.", "format": "date-time" }, "next_validation_at": { "type": "string", "description": "server_time plus product interval hours.", "format": "date-time" }, "offline_grace_until": { "type": "string", "description": "server_time plus grace hours, not added after the validation interval.", "format": "date-time" } }, "required": [ "license_id", "product_id", "product", "plan", "status", "environment", "expires_at", "license_key_mask", "starts_at", "created_at", "max_devices", "max_activations", "activation_count", "min_version", "max_version", "active_devices", "customer", "product_details", "plan_details", "features", "device", "server_time", "next_validation_at", "offline_grace_until" ], "additionalProperties": false }, "SignedEnvelope": { "type": "object", "description": "Only payload is signed. This is PHP-specific canonical JSON, not RFC8785.", "properties": { "payload": { "$ref": "#/components/schemas/LicensePayload" }, "signature": { "type": "string", "description": "Unpadded base64url Ed25519 signature over canonical payload bytes.", "pattern": "^[A-Za-z0-9_-]{86}$" }, "algorithm": { "type": "string", "description": "Fixed algorithm, not negotiated.", "const": "Ed25519" }, "key_id": { "type": "string", "description": "Must equal independently trusted key ID." } }, "required": [ "payload", "signature", "algorithm", "key_id" ], "additionalProperties": false }, "LicenseSummary": { "type": "object", "description": "Unsigned management summary; no full license key or activation token.", "properties": { "id": { "type": "string", "description": "License identifier." }, "license_key_mask": { "type": "string", "description": "Display-only masked key." }, "status": { "type": "string", "description": "Lowercase stored license status.", "enum": [ "active", "suspended", "revoked", "expired", "pending", "cancelled" ] }, "environment": { "type": "string", "description": "Bound environment.", "enum": [ "sandbox", "live" ] }, "starts_at": { "type": [ "string", "null" ], "description": "Configured start.", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "description": "Configured expiry.", "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp.", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "description": "Last stored update.", "format": "date-time" }, "max_devices": { "type": "integer", "description": "Concurrent device limit." }, "active_devices": { "type": "integer", "description": "Active device count." }, "max_activations": { "type": [ "integer", "null" ], "description": "Cumulative activation cap." }, "activation_count": { "type": "integer", "description": "Consumed activations." }, "min_version": { "type": [ "string", "null" ], "description": "Lower version bound." }, "max_version": { "type": [ "string", "null" ], "description": "Upper version bound." }, "revocation_reason": { "type": [ "string", "null" ], "description": "Optional reason." }, "product": { "type": "object", "description": "Product summary.", "properties": { "id": { "type": "string", "description": "Public App ID." }, "name": { "type": "string", "description": "Product name." } }, "required": [ "id", "name" ], "additionalProperties": false }, "plan": { "type": "object", "description": "Plan summary.", "properties": { "id": { "type": "string", "description": "Internal product-plan identifier." }, "name": { "type": "string", "description": "Plan display name." }, "slug": { "type": "string", "description": "Plan slug." }, "billing_type": { "type": "string", "description": "Lowercase product-plan billing type." }, "price": { "type": "number", "description": "PHP float; preserve numeric tokens such as19.0 for signatures." }, "currency": { "type": "string", "description": "Configured product-plan currency." } }, "required": [ "id", "name", "slug", "billing_type", "price", "currency" ], "additionalProperties": false }, "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "id", "license_key_mask", "status", "environment", "starts_at", "expires_at", "created_at", "updated_at", "max_devices", "active_devices", "max_activations", "activation_count", "min_version", "max_version", "revocation_reason", "product", "plan", "customer" ], "additionalProperties": false }, "KeyResponse": { "type": "object", "description": "Current verification key response.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "key": { "$ref": "#/components/schemas/PublicKey" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "key", "request_id" ], "additionalProperties": false }, "CreateResponse": { "type": "object", "description": "License creation HTTP201 response.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "license": { "type": "object", "description": "Newly issued license credential.", "properties": { "id": { "type": "string", "description": "Created license identifier." }, "license_key": { "type": "string", "description": "Complete newly generated secret; save securely. Returned on stored create replay too." }, "expires_at": { "type": [ "string", "null" ], "description": "Calculated expiry.", "format": "date-time" }, "environment": { "type": "string", "description": "Developer-key environment.", "enum": [ "sandbox", "live" ] } }, "required": [ "id", "license_key", "expires_at", "environment" ], "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "license", "request_id" ], "additionalProperties": false }, "ActivateResponse": { "type": "object", "description": "Activated installation and signed snapshot.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "activation_token": { "type": "string", "description": "act_ plus43 base64url characters; installation secret, do not log." }, "license": { "$ref": "#/components/schemas/SignedEnvelope" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "activation_token", "license", "request_id" ], "additionalProperties": false }, "ValidateResponse": { "type": "object", "description": "Validated installation response.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "valid": { "type": "boolean", "const": true, "description": "Server accepted this validation; still verify the signed snapshot." }, "license": { "$ref": "#/components/schemas/SignedEnvelope" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "valid", "license", "request_id" ], "additionalProperties": false }, "DeactivateResponse": { "type": "object", "description": "Successful device deactivation.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "deactivated": { "type": "boolean", "const": true, "description": "Device seat released; cumulative count is unchanged." }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "deactivated", "request_id" ], "additionalProperties": false }, "GetResponse": { "type": "object", "description": "Scoped management read.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "license": { "$ref": "#/components/schemas/LicenseSummary" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "license", "request_id" ], "additionalProperties": false }, "StatusResponse": { "type": "object", "description": "Management status transition.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "license": { "type": "object", "description": "State result; old revoked tokens do not revive.", "properties": { "id": { "type": "string", "description": "License identifier." }, "status": { "type": "string", "description": "Resulting state.", "enum": [ "active", "suspended", "revoked" ] } }, "required": [ "id", "status" ], "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "license", "request_id" ], "additionalProperties": false }, "RenewResponse": { "type": "object", "description": "Expiry extension, not a payment or plan change.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "license": { "type": "object", "description": "Renewal result.", "properties": { "id": { "type": "string", "description": "License identifier." }, "status": { "type": "string", "description": "Resulting state; suspended/pending remain so.", "enum": [ "active", "suspended", "pending" ] }, "expires_at": { "type": [ "string", "null" ], "description": "Extended expiration.", "format": "date-time" } }, "required": [ "id", "status", "expires_at" ], "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "license", "request_id" ], "additionalProperties": false }, "ResetResponse": { "type": "object", "description": "Device-reset result.", "properties": { "success": { "type": "boolean", "const": true, "description": "The operation succeeded." }, "devices_reset": { "type": "boolean", "const": true, "description": "Active devices released and tokens revoked; cumulative count unchanged." }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "devices_reset", "request_id" ], "additionalProperties": false }, "Error": { "type": "object", "description": "Licensing API error; not the separate billing/operational error formats.", "properties": { "success": { "type": "boolean", "const": false, "description": "The operation failed." }, "error": { "type": "object", "description": "Error detail.", "properties": { "code": { "type": "string", "description": "Machine-readable error identifier." }, "message": { "type": "string", "description": "Human-readable server message; do not use text as a stable code." } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "success", "error", "request_id" ], "additionalProperties": false }, "CreateRequest": { "type": "object", "description": "Recommended JSON input. Backend casts strings and ignores unknown fields.", "properties": { "product_id": { "type": "string", "description": "Internal ID or slug of the developer key product; not public App ID.", "minLength": 2, "maxLength": 190 }, "plan_id": { "type": "string", "description": "Active product-plan ID or slug.", "minLength": 2, "maxLength": 140 }, "customer": { "type": "object", "description": "Customer fields; country/metadata are not consumed.", "properties": { "email": { "type": "string", "description": "Normalized trimmed lowercase email; required.", "format": "email", "maxLength": 190 }, "name": { "type": "string", "description": "Optional trimmed name; invalid length becomes empty.", "maxLength": 160 }, "company": { "type": "string", "description": "Optional trimmed company; invalid length becomes empty.", "maxLength": 160 }, "external_id": { "type": "string", "description": "Optional external customer ID; invalid length becomes empty.", "maxLength": 190 } }, "required": [ "email" ], "additionalProperties": true } }, "required": [ "product_id", "plan_id", "customer" ], "additionalProperties": true }, "ActivateRequest": { "type": "object", "description": "Recommended activation JSON. Strings are trimmed by the backend.", "properties": { "license_key": { "type": "string", "description": "Customer license key; case-insensitive hashed lookup.", "minLength": 12, "maxLength": 100 }, "device_id": { "type": "string", "description": "Persisted random installation ID.", "minLength": 16, "maxLength": 255 }, "email": { "type": "string", "description": "Optional; nonempty normalized email must match the license customer.", "maxLength": 190 }, "device_name": { "type": "string", "description": "Optional descriptive label; invalid length becomes empty.", "maxLength": 160 }, "platform": { "type": "string", "description": "Optional description, no OS enum.", "maxLength": 50 }, "app_version": { "type": "string", "description": "Optional version; empty bypasses version-range check.", "maxLength": 30 } }, "required": [ "license_key", "device_id" ], "additionalProperties": true }, "ReasonRequest": { "type": "object", "description": "Reason consumed for status actions; unknown fields ignored.", "properties": { "reason": { "type": "string", "description": "Optional trimmed reason; invalid length becomes null.", "maxLength": 190 } }, "required": [], "additionalProperties": true }, "RenewRequest": { "type": "object", "description": "Recommended integer input; backend FILTER_VALIDATE_INT also accepts certain numeric strings.", "properties": { "days": { "type": "integer", "description": "Days added to future expiry or current server time;1–3650.", "minimum": 1, "maximum": 3650 } }, "required": [ "days" ], "additionalProperties": true }, "EmptyRequest": { "type": "object", "description": "No body fields consumed; omit the body or send{}.", "properties": {}, "required": [], "additionalProperties": true } } }, "externalDocs": { "description": "KDPika Licensing public documentation.", "url": "https://licensing.kdpika.com/docs" }, "x-source-hashes": { "public_html/index.php": "8b45b7cd06afde27ef8bc5b8904ebc0bcfaf5f010354b0a93c02f66f24d3198b", "app/Controllers/Api/V1/PhaseTwoController.php": "4efd849eb8469f13724bea07516bb3e9e4b9d7158ba8fb9130ab13f19bfb4dd0", "app/Core/Request.php": "071d76e1f366b0cf98f80612221b95319b67394b8315c3ae2c7d4698701ebc28", "app/Core/Response.php": "63c170a680d331a79fdde6d9960336ab35c3cd5ccd058a49524100731c48c498", "app/Core/Router.php": "5f4c3885697a7305117158ac8cb14982a87e94116fdff7b4331682dd0f0c2d81", "app/Core/Validator.php": "52ac7528d7583a60190746247dba97d2604428f5bea5b2845b2b8ab7bc1d9d34", "app/Services/LicenseEngine.php": "d124436fd34a631264396c4f13774725c0dfc36d6f2e7d09bf81fb5978e0b94f", "app/Services/LicenseService.php": "3924268491a02deef039745770f02c975ded71af5d42c5f8e301e13b9ddb629f", "app/Services/DeviceService.php": "c83601200408290bd59195ec60299f39e0fc2eb015630f9f66dac57f8671e347", "app/Services/ApiKeyService.php": "021fd676e809e65d7a1be56dd118d636037bee215419c0d6682476f202fc7348", "app/Services/IdempotencyService.php": "5487ac3afe6893b9a6d0cbd2127b64fc56f93d4b6b6b9bbe1decc21cd29e85fc", "app/Services/RateLimiter.php": "ae0c3ba3dbd0cb24ce74ff70cc2becab4b4bcdd9db5740cc96b1a3a3fcd05e90" }, "x-router-errors": { "NOT_FOUND": 404, "INTERNAL_ERROR": 500 }, "x-input-contract": "Schemas describe supported recommended JSON inputs; permissive PHP casts/alternate forms are documented, not redefined." }