--- title: "Create a license" description: "Issue a license after your backend verifies the buyer purchase." slug: "/docs/v1/api/create-license" section: "API reference" order: 27 audience: "all" level: "intermediate" last_updated: "2026-10-17" version: "v1" related: ["/docs/v1/api/conventions", "/docs/v1/start/authentication"] draft: false --- Issue a [license](/docs/v1/start/glossary#license) after your backend verifies the buyer purchase. ## What you will learn - Send this exact operation with its required credentials and fields. - Interpret success, refusal, side effects and retry risks. ## Prerequisites - Complete [the Sandbox quickstart](/docs/v1/start/quickstart). - Read [API conventions](/docs/v1/api/conventions) and [authentication](/docs/v1/start/authentication). - Keep [customer](/docs/v1/start/glossary#customer) credentials private and management keys on your trusted backend. ## Method and path POST /api/v1/licenses ### When to use it Issue a buyer license from your trusted backend after your own store verifies the purchase. KDPika does not collect payment from your software buyers or verify their store receipt on this endpoint. ## Authentication and environment Use Authorization: Bearer YOUR_DEVELOPER_API_KEY with [scope](/docs/v1/start/glossary#scope) licenses:write. The key fixes the [organization](/docs/v1/start/glossary#organization)/[product](/docs/v1/start/glossary#product)/environment; X-Environment cannot override it. ## Request headers | Header | Required | Description | Example | | --- | --- | --- | --- | | Accept | recommended | JSON responses | application/json | | Content-Type | for JSON body | Use the documented JSON object | application/json | | Authorization | yes | Scoped backend-only [developer](/docs/v1/start/glossary#developer) key | Bearer YOUR_DEVELOPER_API_KEY | | Idempotency-Key | yes | Stable organization-scoped business-event key,8–190 trimmed characters; retention24hours, known expiry/concurrency limits. | YOUR_STABLE_BUSINESS_EVENT_ID | ## Path and query parameters No path parameters are accepted. No pagination, filtering, sorting or list query parameters are implemented. Use JSON rather than relying on alternate form/query parsing. ## Request body | Field | Type | Required | Constraints/default | Description | Example | | --- | --- | --- | --- | --- | --- | | product_id | string | yes | minLength=2; maxLength=190 | Internal ID or slug of the developer key product; not [public App ID](/docs/v1/start/glossary#public-app-id). | "YOUR_INTERNAL_PRODUCT_ID" | | plan_id | string | yes | minLength=2; maxLength=140 | Active product-plan ID or slug. | "YOUR_PRODUCT_PLAN_ID" | | customer | object | yes | See description | Customer fields; country/metadata are not consumed. | Nested object/array shown in full JSON | | customer.email | string | yes | maxLength=190; format="email" | Normalized trimmed lowercase email; required. | "customer@example.invalid" | | customer.name | string | no | maxLength=160 | Optional trimmed name; invalid length becomes empty. | "Example customer" | | customer.company | string | no | maxLength=160 | Optional trimmed company; invalid length becomes empty. | "Example company" | | customer.external_id | string | no | maxLength=190 | Optional external customer ID; invalid length becomes empty. | "YOUR_CUSTOMER_REFERENCE" | ### Full request JSON ```json { "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" } } ``` The schemas describe supported recommended input types. Current PHP parsing trims/casts strings and may ignore unknown fields; it is not strict JSON-schema validation. Invalid optional descriptive fields can become empty/null. [Conventions](/docs/v1/api/conventions) describes malformed JSON and alternate parsing. ## Success response HTTP 201. The following is a real isolated Sandbox capture; secret values are replaced with explicit placeholders. ```json { "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" } ``` ### Response fields | Field | Type | Required | Constraints | Description | Example | | --- | --- | --- | --- | --- | --- | | success | boolean | yes | const=true | The operation succeeded. | true | | license | object | yes | See description | Newly issued license credential. | Nested object/array shown in full JSON | | license.id | string | yes | See description | Created license identifier. | "lic_578581bd80c2a672da30fc29" | | license.license_key | string | yes | See description | Complete newly generated secret; save securely. Returned on stored create replay too. | "YOUR_NEW_LICENSE_KEY" | | license.expires_at | string or null | yes | format="date-time" | Calculated expiry. | "2026-11-16T10:39:35+00:00" | | license.environment | string | yes | enum=["sandbox", "[live](/docs/v1/start/glossary#live)"] | Developer-key environment. | "sandbox" | | request_id | string | yes | pattern="^req_[a-f0-9]{24}$" | Request correlation ID. Replay bodies can retain an earlier ID. | "req_1c0f804fd7c455f25fa1f791" | ### Response headers X-Request-ID identifies the current request. Successful limited calls include X-RateLimit-Remaining and X-RateLimit-Reset, the latter in Unix seconds. Errors omit those rate headers and Retry-After. See the complete [rate-limit reference](/docs/v1/api/rate-limits). ## Error responses | Code | HTTP | Cause | Fix | Retryable? | | --- | --- | --- | --- | --- | | INVALID_REQUEST | 422 | Input constraints or entitlement/resource/renewal domain rejection | Correct input/plan; not blind retry | No blind retry; apply the correction | | PLAN_NOT_FOUND | 404 | Create product/plan does not resolve within active API-key product | Correct scoped IDs | No blind retry; apply the correction | | IDEMPOTENCY_CONFLICT | 409 | Organization key reused with different decoded-body hash (member order matters) | Use same body; new key only for new operation | No blind retry; apply the correction | | INTERNAL_ERROR | 500 | Uncaught exception at global boundary | Safe retry only for idempotent operation; preserve request_id | Only safe reads after backoff; reconcile mutations | | INVALID_API_KEY | 401 | Missing/invalid/revoked key or prohibited subscription/environment | Replace/configure key | No blind retry; apply the correction | | FORBIDDEN | 403 | Developer scope missing; checkout account role not OWNER/ADMIN | Use authorized scope/role | No blind retry; apply the correction | | RATE_LIMITED | 429 | Bucket exhausted; wait for window reset; no licensing Retry-After header | After window; apply jitter | After the 60-second window, with jitter | An unregistered path or wrong method is handled by the global router as NOT_FOUND (HTTP 404), not405. Every licensing error has success=false, error.code, error.message and request_id. [Errors](/docs/v1/api/errors) keeps SDK-local and operational namespaces separate. ## Side effects Creates one ACTIVE license and, if needed, one customer scoped by organization/environment/email. An existing customer's descriptive fields are not updated by this call. Duration/trial policy comes from the [product plan](/docs/v1/start/glossary#product-plan). Creates audit license.created and queues [webhook](/docs/v1/start/glossary#webhook) license.created for matching configured endpoints; no email is sent directly. A stored replay does not issue another license or repeat those creation events. Active-license capacity is checked before creation. The new plaintext key is included in the retained idempotency response for 24 hours; do not call this no-plaintext storage. Authenticated requests can consume the organization monthly API usage counter once tenant context is established, including some failures. This usage counter is currently warning-only, not a monthly API rejection gate. Developer-key authentication can update last_used_at before a later failure. No request body or Authorization value is saved by the API metadata logger. ## Idempotency and concurrency An 8–190 character Idempotency-Key is mandatory and scoped to the organization, not a single product. The retention window is24 hours. The hash covers PHP JSON encoding of the decoded body; changed member order can conflict. A stored replay returns 201, the original body/request_id/key and Idempotent-Replay:true, with a new current X-Request-ID header. Known expiry/concurrency defects can commit duplicate licenses before 500. Serialize fulfillment by business event on your backend, preserve your durable mapping and reconcile uncertain outcomes instead of blindly choosing a new key. This is not an exactly-once guarantee. ## Rate limits Developer pre-authentication:240 requests per60 seconds per IP. After successful authentication/scope checks:60 per60 seconds per developer-key license-create bucket. Fixed windows begin with the first hit after expiry. Attempted calls consume every bucket they reach, even if later business validation fails. ## Runnable examples These are complete native HTTP transport programs, not full SDK clients or entitlement verifiers. JSON request bodies and credentials come from KDP_* environment variables. They print raw responses to a private terminal; do not send their stdout to application/CI logs. Use the [P5 verification guides](/docs/v1/security/verify-ed25519) before granting access. Run sh request.sh create-license. ### cURL ```curl #!/bin/sh # Purpose: inspect one Sandbox API operation; not signature verification. # Requirements: POSIX sh, curl7.76+. Run: sh request.sh public-key # Expected: JSON; exit0 HTTP2xx/1 HTTP rejection/2 setup or transport failure. # KDP_* variables carry credentials/body. Output can contain newly issued secrets: # use a private terminal only, never application/CI logs. Verify signed state separately. set -eu fail() { printf '%s\n' 'Check the operation and KDP_* configuration. Do not blindly retry mutations.' >&2; exit 2; } [ "$#" -eq 1 ] || fail name=$1 case "$name" in public-key) method='GET'; path='/public-key'; auth='public' ;; create-license) method='POST'; path='/licenses'; auth='developer' ;; activate) method='POST'; path='/licenses/activate'; auth='publicApp' ;; validate) method='POST'; path='/licenses/validate'; auth='activation' ;; deactivate) method='POST'; path='/licenses/deactivate'; auth='activation' ;; get-license) method='GET'; path='/licenses/{license}'; auth='developer' ;; revoke) method='POST'; path='/licenses/{license}/revoke'; auth='developer' ;; suspend) method='POST'; path='/licenses/{license}/suspend'; auth='developer' ;; restore) method='POST'; path='/licenses/{license}/restore'; auth='developer' ;; renew) method='POST'; path='/licenses/{license}/renew'; auth='developer' ;; reset-devices) method='POST'; path='/licenses/{license}/reset-devices'; auth='developer' ;; *) fail ;; esac base=${KDP_BASE_URL:-https://licensing.kdpika.com/api/v1} base=${base%/} case "$base" in *'@'*|*'?'*|*'#'*|*' '* ) fail ;; esac case "$base" in https://*/api/v1) ;; http://127.0.0.1:*/api/v1|http://localhost:*/api/v1) [ "${KDP_ALLOW_LOOPBACK:-0}" = 1 ] || fail ;; *) fail ;; esac case "$path" in *'{license}'*) id=${KDP_LICENSE_ID:?Set KDP_LICENSE_ID} case "$id" in *[!A-Za-z0-9_-]*|'') fail ;; esac path=$(printf '%s' "$path" | sed "s/{license}/$id/") ;; esac set -- --silent --show-error --fail-with-body --connect-timeout 5 --max-time 15 --request "$method" \ --header 'Accept: application/json' --header 'User-Agent: KDPikaDocsExample/1.0 curl' case "$auth" in developer) case "${KDP_API_KEY:-}" in lmp_sandbox_*) ;; *) fail ;; esac set -- "$@" --header "Authorization: Bearer $KDP_API_KEY" ;; activation) set -- "$@" --header "Authorization: Bearer ${KDP_ACTIVATION_TOKEN:?Set KDP_ACTIVATION_TOKEN}" ;; publicApp) set -- "$@" --header "X-App-ID: ${KDP_APP_ID:?Set KDP_APP_ID}" --header 'X-Environment: SANDBOX' ;; esac if [ "$name" = create-license ]; then set -- "$@" --header "Idempotency-Key: ${KDP_IDEMPOTENCY_KEY:?Set KDP_IDEMPOTENCY_KEY}"; fi if [ "$name" = validate ]; then set -- "$@" --header "X-Installation-ID: ${KDP_INSTALLATION_ID:?Set KDP_INSTALLATION_ID}"; fi if [ "$method" = POST ]; then body=${KDP_BODY_JSON-'{}'} set -- "$@" --header 'Content-Type: application/json' --data-binary "$body" fi # Keep the response in memory only, separating the final status line. No file, # --location, --insecure or --verbose. The caller must still inspect JSON success. if response=$(curl "$@" --write-out '\n%{http_code}' "$base$path"); then transport=0; else transport=$?; fi newline=' ' status=${response##*"$newline"} payload=${response%"$newline"*} case "$status" in [0-9][0-9][0-9]) ;; *) fail ;; esac if [ "$transport" -ne 0 ] && [ "$transport" -ne 22 ]; then fail; fi printf '%s\n' "$payload" case "$status" in 2[0-9][0-9]) exit 0 ;; esac printf '%s\n' 'The API did not accept the request. Inspect error.code/request_id; reconcile mutations before retrying.' >&2 exit 1 ``` Run python3 request.py create-license. ### Python ```python """Inspect one Sandbox API operation; transport example, not access authorization. Requires Python3.9+ standard library. Run: python3 request.py public-key Expected: full API JSON on stdout; exit0 on success,1 on API rejection,2 on setup/transport failure. Credentials/body via KDP_* environment variables. Stdout may contain new secrets: use only a private terminal, never application/CI logs. Verify signed state separately. """ import json import os import re import sys from urllib.error import HTTPError from urllib.parse import urlsplit from urllib.request import HTTPRedirectHandler, Request, build_opener # Preserve raw UTF-8 JSON even when piped on a non-UTF-8 Windows console. sys.stdout.reconfigure(encoding='utf-8') OPERATIONS = json.loads(r'''{ "public-key": { "method": "GET", "path": "/public-key", "auth": "public" }, "create-license": { "method": "POST", "path": "/licenses", "auth": "developer" }, "activate": { "method": "POST", "path": "/licenses/activate", "auth": "publicApp" }, "validate": { "method": "POST", "path": "/licenses/validate", "auth": "activation" }, "deactivate": { "method": "POST", "path": "/licenses/deactivate", "auth": "activation" }, "get-license": { "method": "GET", "path": "/licenses/{license}", "auth": "developer" }, "revoke": { "method": "POST", "path": "/licenses/{license}/revoke", "auth": "developer" }, "suspend": { "method": "POST", "path": "/licenses/{license}/suspend", "auth": "developer" }, "restore": { "method": "POST", "path": "/licenses/{license}/restore", "auth": "developer" }, "renew": { "method": "POST", "path": "/licenses/{license}/renew", "auth": "developer" }, "reset-devices": { "method": "POST", "path": "/licenses/{license}/reset-devices", "auth": "developer" } }''') def required(name): value = os.environ.get(name, '') if not value or '\r' in value or '\n' in value: raise ValueError('Set a valid ' + name + '.') return value class NoRedirect(HTTPRedirectHandler): def redirect_request(self, request, file, code, message, headers, new_url): return None def main(): if len(sys.argv) != 2 or sys.argv[1] not in OPERATIONS: raise ValueError('Choose an operation: ' + ', '.join(OPERATIONS)) operation = OPERATIONS[sys.argv[1]] base = os.environ.get('KDP_BASE_URL', 'https://licensing.kdpika.com/api/v1').rstrip('/') parsed = urlsplit(base) loopback = parsed.scheme == 'http' and parsed.hostname in ('127.0.0.1', 'localhost') and os.environ.get('KDP_ALLOW_LOOPBACK') == '1' if not parsed.hostname or (parsed.scheme != 'https' and not loopback) or parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path != '/api/v1': raise ValueError('Use an HTTPS API base URL ending in /api/v1. Loopback HTTP needs explicit test opt-in.') path = operation['path'] if '{license}' in path: identifier = required('KDP_LICENSE_ID') if not re.fullmatch(r'[A-Za-z0-9_-]+', identifier): raise ValueError('This sample accepts the simple license IDs issued by the platform.') path = path.replace('{license}', identifier) headers = {'Accept': 'application/json', 'User-Agent': 'KDPikaDocsExample/1.0 Python'} if operation['auth'] == 'developer': key = required('KDP_API_KEY') if not key.startswith('lmp_sandbox_'): raise ValueError('Use a Sandbox developer API key with this example.') headers['Authorization'] = 'Bearer ' + key elif operation['auth'] == 'activation': headers['Authorization'] = 'Bearer ' + required('KDP_ACTIVATION_TOKEN') elif operation['auth'] == 'publicApp': headers.update({'X-App-ID': required('KDP_APP_ID'), 'X-Environment': 'SANDBOX'}) if sys.argv[1] == 'create-license': headers['Idempotency-Key'] = required('KDP_IDEMPOTENCY_KEY') if sys.argv[1] == 'validate': headers['X-Installation-ID'] = required('KDP_INSTALLATION_ID') body = None if operation['method'] == 'POST': source = os.environ.get('KDP_BODY_JSON', '{}') if not isinstance(json.loads(source), dict): raise ValueError('KDP_BODY_JSON must be a JSON object.') body = source.encode('utf-8') headers['Content-Type'] = 'application/json' request = Request(base + path, data=body, headers=headers, method=operation['method']) try: response = build_opener(NoRedirect()).open(request, timeout=15) except HTTPError as error: response = error raw = response.read().decode('utf-8') result = json.loads(raw) sys.stdout.write(raw + '\n') if not (200 <= response.status < 300 and result.get('success') is True): sys.stderr.write('The API rejected this request. Check error.code and request_id; do not blindly retry a mutation.\n') return 1 return 0 if __name__ == '__main__': try: sys.exit(main()) except ValueError as error: # Configuration errors never interpolate credential values. sys.stderr.write(str(error) if str(error).startswith(('Set a valid KDP_', 'Choose an operation:', 'Use ', 'This sample ', 'KDP_BODY_JSON ')) else 'The response or request was not valid JSON.') sys.stderr.write('\n') sys.exit(2) except Exception: sys.stderr.write('Request unavailable. Check connectivity; reconcile uncertain mutations before retrying.\n') sys.exit(2) ``` Run node request.mjs create-license. ### JavaScript (Node) ```javascript // Purpose: inspect one Sandbox API operation; not an entitlement verifier. // Requirements: Node18.20+ native fetch, trusted server/Electron main process. // Run: node request.mjs public-key. Expected: JSON; exit0 success/1 rejection/2 transport or setup. // Credentials/body use KDP_* environment variables. Output can contain new secrets. // Use a private terminal, never application/CI logs. Verify signed state separately. const operations = Object.freeze({ "public-key": { "method": "GET", "path": "/public-key", "auth": "public" }, "create-license": { "method": "POST", "path": "/licenses", "auth": "developer" }, "activate": { "method": "POST", "path": "/licenses/activate", "auth": "publicApp" }, "validate": { "method": "POST", "path": "/licenses/validate", "auth": "activation" }, "deactivate": { "method": "POST", "path": "/licenses/deactivate", "auth": "activation" }, "get-license": { "method": "GET", "path": "/licenses/{license}", "auth": "developer" }, "revoke": { "method": "POST", "path": "/licenses/{license}/revoke", "auth": "developer" }, "suspend": { "method": "POST", "path": "/licenses/{license}/suspend", "auth": "developer" }, "restore": { "method": "POST", "path": "/licenses/{license}/restore", "auth": "developer" }, "renew": { "method": "POST", "path": "/licenses/{license}/renew", "auth": "developer" }, "reset-devices": { "method": "POST", "path": "/licenses/{license}/reset-devices", "auth": "developer" } }); function required(name) { const value = process.env[name]; if (!value || /[\r\n]/.test(value)) throw new Error(`Set a valid ${name}.`); return value; } async function main() { const name = process.argv[2]; if (process.argv.length !== 3 || !Object.hasOwn(operations, name)) throw new Error('Choose a documented operation.'); const operation = operations[name]; const base = (process.env.KDP_BASE_URL || 'https://licensing.kdpika.com/api/v1').replace(/\/+$/, ''); const url = new URL(base); const loopback = url.protocol === 'http:' && ['127.0.0.1', 'localhost'].includes(url.hostname) && process.env.KDP_ALLOW_LOOPBACK === '1'; if ((url.protocol !== 'https:' && !loopback) || url.username || url.password || url.search || url.hash || url.pathname !== '/api/v1') throw new Error('Use an HTTPS API URL ending in /api/v1; loopback HTTP requires explicit test opt-in.'); let path = operation.path; if (path.includes('{license}')) { const id = required('KDP_LICENSE_ID'); if (!/^[A-Za-z0-9_-]+$/.test(id)) throw new Error('Use the simple license ID issued by this platform with this sample.'); path = path.replace('{license}', id); } const headers = {'Accept': 'application/json', 'User-Agent': 'KDPikaDocsExample/1.0 Node'}; if (operation.auth === 'developer') { const key = required('KDP_API_KEY'); if (!key.startsWith('lmp_sandbox_')) throw new Error('Use a Sandbox developer key.'); headers.Authorization = `Bearer ${key}`; } else if (operation.auth === 'activation') headers.Authorization = `Bearer ${required('KDP_ACTIVATION_TOKEN')}`; else if (operation.auth === 'publicApp') { headers['X-App-ID'] = required('KDP_APP_ID'); headers['X-Environment'] = 'SANDBOX'; } if (name === 'create-license') headers['Idempotency-Key'] = required('KDP_IDEMPOTENCY_KEY'); if (name === 'validate') headers['X-Installation-ID'] = required('KDP_INSTALLATION_ID'); let body; if (operation.method === 'POST') { body = process.env.KDP_BODY_JSON || '{}'; const value = JSON.parse(body); if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('KDP_BODY_JSON must be a JSON object.'); headers['Content-Type'] = 'application/json'; } const response = await fetch(base + path, {method: operation.method, headers, body, redirect: 'error', signal: AbortSignal.timeout(15000)}); const raw = await response.text(); const result = JSON.parse(raw); process.stdout.write(raw + '\n'); if (!response.ok || result.success !== true) { process.stderr.write('The API rejected this request. Inspect error.code and request_id; reconcile mutations before retrying.\n'); return 1; } return 0; } main().then(code => {process.exitCode = code;}).catch(() => { process.stderr.write('Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.\n'); process.exitCode = 2; }); ``` Run php request.php create-license. ### PHP ```php true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 15, CURLOPT_SSL_VERIFYPEER => true, CURLOPT_SSL_VERIFYHOST => 2, CURLOPT_CUSTOMREQUEST => $operation['method']]; if ($operation['method'] === 'POST') { $body = getenv('KDP_BODY_JSON') ?: '{}'; if (!is_object(json_decode($body, false, 512, JSON_THROW_ON_ERROR))) throw new RuntimeException('JSON object required.'); $headers[] = 'Content-Type: application/json'; $options[CURLOPT_POSTFIELDS] = $body; } $options[CURLOPT_HTTPHEADER] = $headers; curl_setopt_array($curl, $options); $raw = curl_exec($curl); if ($raw === false) throw new RuntimeException('Transport unavailable.'); $status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE); // No curl_close: PHP objects release the handle; PHP8.5 deprecates that call. $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); echo $raw . "\n"; if ($status < 200 || $status >= 300 || ($result['success'] ?? null) !== true) { fwrite(STDERR, "The API rejected this request. Inspect error.code/request_id; reconcile mutations before retrying.\n"); exit(1); } exit(0); } catch (Throwable) { fwrite(STDERR, "Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.\n"); exit(2); } ``` Run dotnet run --project ApiExample.csproj -- create-license. ### C# ```csharp // Purpose: inspect one Sandbox API operation; transport only, not feature access. // Requirements: .NET7+ console project. Run: dotnet run -- public-key // Expected: JSON; exit0 success/1 API rejection/2 setup or transport failure. // KDP_* environment variables carry credentials/body. Stdout can contain new secrets: // use a private terminal, never application/CI logs. Verify signed state separately. using System.Net.Http.Headers; using System.Text; using System.Text.Json; using System.Text.RegularExpressions; Console.OutputEncoding = new UTF8Encoding(false); const string Contract = """ { "public-key": { "method": "GET", "path": "/public-key", "auth": "public" }, "create-license": { "method": "POST", "path": "/licenses", "auth": "developer" }, "activate": { "method": "POST", "path": "/licenses/activate", "auth": "publicApp" }, "validate": { "method": "POST", "path": "/licenses/validate", "auth": "activation" }, "deactivate": { "method": "POST", "path": "/licenses/deactivate", "auth": "activation" }, "get-license": { "method": "GET", "path": "/licenses/{license}", "auth": "developer" }, "revoke": { "method": "POST", "path": "/licenses/{license}/revoke", "auth": "developer" }, "suspend": { "method": "POST", "path": "/licenses/{license}/suspend", "auth": "developer" }, "restore": { "method": "POST", "path": "/licenses/{license}/restore", "auth": "developer" }, "renew": { "method": "POST", "path": "/licenses/{license}/renew", "auth": "developer" }, "reset-devices": { "method": "POST", "path": "/licenses/{license}/reset-devices", "auth": "developer" } } """; try { using var operations = JsonDocument.Parse(Contract); if (args.Length != 1 || !operations.RootElement.TryGetProperty(args[0], out var operation)) throw new Exception("Invalid operation."); var name = args[0]; string Required(string key) { var value = Environment.GetEnvironmentVariable(key); if (String.IsNullOrEmpty(value) || value.Contains('\r') || value.Contains('\n')) throw new Exception("Missing configuration."); return value; } var root = (Environment.GetEnvironmentVariable("KDP_BASE_URL") ?? "https://licensing.kdpika.com/api/v1").TrimEnd('/'); var uri = new Uri(root); var loopback = uri.Scheme == "http" && (uri.Host == "127.0.0.1" || uri.Host == "localhost") && Environment.GetEnvironmentVariable("KDP_ALLOW_LOOPBACK") == "1"; if ((uri.Scheme != "https" && !loopback) || uri.UserInfo != "" || uri.Query != "" || uri.Fragment != "" || uri.AbsolutePath != "/api/v1") throw new Exception("Invalid base URL."); var path = operation.GetProperty("path").GetString()!; if (path.Contains("{license}")) { var identifier = Required("KDP_LICENSE_ID"); if (!Regex.IsMatch(identifier, "^[A-Za-z0-9_-]+$")) throw new Exception("Unsupported sample identifier."); path = path.Replace("{license}", identifier); } using var handler = new HttpClientHandler {AllowAutoRedirect = false}; using var client = new HttpClient(handler) {Timeout = TimeSpan.FromSeconds(15)}; using var request = new HttpRequestMessage(new HttpMethod(operation.GetProperty("method").GetString()!), root + path); request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json")); request.Headers.UserAgent.ParseAdd("KDPikaDocsExample/1.0 CSharp"); var auth = operation.GetProperty("auth").GetString(); if (auth == "developer") { var key = Required("KDP_API_KEY"); if (!key.StartsWith("lmp_sandbox_", StringComparison.Ordinal)) throw new Exception("Sandbox key required."); request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", key); } else if (auth == "activation") request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Required("KDP_ACTIVATION_TOKEN")); else if (auth == "publicApp") { request.Headers.Add("X-App-ID", Required("KDP_APP_ID")); request.Headers.Add("X-Environment", "SANDBOX"); } if (name == "create-license") request.Headers.Add("Idempotency-Key", Required("KDP_IDEMPOTENCY_KEY")); if (name == "validate") request.Headers.Add("X-Installation-ID", Required("KDP_INSTALLATION_ID")); if (request.Method == HttpMethod.Post) { var body = Environment.GetEnvironmentVariable("KDP_BODY_JSON") ?? "{}"; using var parsedBody = JsonDocument.Parse(body); if (parsedBody.RootElement.ValueKind != JsonValueKind.Object) throw new Exception("JSON object required."); request.Content = new StringContent(body, Encoding.UTF8, "application/json"); } using var response = await client.SendAsync(request); var raw = await response.Content.ReadAsStringAsync(); using var result = JsonDocument.Parse(raw); Console.WriteLine(raw); if (!response.IsSuccessStatusCode || !result.RootElement.TryGetProperty("success", out var success) || success.ValueKind != JsonValueKind.True) { Console.Error.WriteLine("The API rejected this request. Inspect error.code/request_id; reconcile mutations before retrying."); return 1; } return 0; } catch (Exception) { Console.Error.WriteLine("Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations."); return 2; } ``` ```csharp Exe net7.0 enable enable ``` ## Expected result A correctly authenticated eligible request returns the documented HTTP status and schema. Check the actual success/error result and [request IDs](/docs/v1/start/glossary#request-id); a successful transport or unsigned management response does not grant a [feature](/docs/v1/start/glossary#feature). ## Common mistakes - Mixing Public App IDs, internal product IDs and product-plan IDs. - Assuming a mutation timeout means no work committed, or assuming Idempotency-Key protects every action. - Logging raw responses that contain a newly issued [license key](/docs/v1/start/glossary#license-key) or [activation token](/docs/v1/start/glossary#activation-token). ## Security notes Keep lmp_ credentials out of shipped desktop/browser code. Verify signed payload bytes and product/environment/installation/status/time/feature policy. The examples do not fix the documented idempotency, cache canonicalization or current-key-only rotation limitations. ## Troubleshooting | Symptom | Cause | Action | | --- | --- | --- | | INVALID_REQUEST (HTTP 422) | Input constraints or entitlement/resource/renewal domain rejection | Correct input/plan; not blind retry | | PLAN_NOT_FOUND (HTTP 404) | Create product/plan does not resolve within active API-key product | Correct scoped IDs | | IDEMPOTENCY_CONFLICT (HTTP 409) | Organization key reused with different decoded-body hash (member order matters) | Use same body; new key only for new operation | | INTERNAL_ERROR (HTTP 500) | Uncaught exception at global boundary | Safe retry only for idempotent operation; preserve request_id | | INVALID_API_KEY (HTTP 401) | Missing/invalid/revoked key or prohibited subscription/environment | Replace/configure key | | FORBIDDEN (HTTP 403) | Developer scope missing; checkout account role not OWNER/ADMIN | Use authorized scope/role | | RATE_LIMITED (HTTP 429) | Bucket exhausted; wait for window reset; no licensing Retry-After header | After window; apply jitter | ## Next steps Read [idempotency](/docs/v1/api/idempotency) and [signed responses](/docs/v1/security/signed-responses) before integrating a purchase-to-license workflow. ## Related - [API conventions](/docs/v1/api/conventions) - [Errors](/docs/v1/api/errors) - [License lifecycle](/docs/v1/start/license-lifecycle)