---
title: "Validate an installation"
description: "Refresh the signed state of an activated installation."
slug: "/docs/v1/api/validate"
section: "API reference"
order: 29
audience: "all"
level: "intermediate"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/api/conventions", "/docs/v1/start/authentication"]
draft: false
---
Refresh the signed state of an activated installation.

## 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](/docs/v1/start/glossary#license)/validate

### When to use it
Refresh the signed state of an activated installation. Send its [activation token](/docs/v1/start/glossary#activation-token) and the exact persisted [installation ID](/docs/v1/start/glossary#installation-id), then verify the returned envelope and semantic policy before enabling [features](/docs/v1/start/glossary#feature).

## Authentication and environment
Use Authorization: Bearer YOUR_ACTIVATION_TOKEN. The token fixes the installation/[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 | Installation token | Bearer YOUR_ACTIVATION_TOKEN |
| X-Installation-ID | no | Always send the persisted ID. Omission signs a null installation hash that official clients reject. | YOUR_PERSISTED_INSTALLATION_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
No body fields are consumed. Omit the body or send an empty object.

### Full request JSON
```json
{}
```

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 200. The following is a real isolated Sandbox capture; secret values are replaced with explicit placeholders.
```json
{
  "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"
}
```

### Response fields
| Field | Type | Required | Constraints | Description | Example |
| --- | --- | --- | --- | --- | --- |
| success | boolean | yes | const=true | The operation succeeded. | true |
| valid | boolean | yes | const=true | Server accepted this validation; still verify the signed snapshot. | true |
| license | object | yes | See description | Only payload is signed. This is PHP-specific canonical JSON, not RFC8785. | Nested object/array shown in full JSON |
| license.payload | object | yes | See description | Exact signed snapshot. Signature authenticity alone does not grant access. | Nested object/array shown in full JSON |
| license.payload.license_id | string | yes | See description | License public identifier. | "lic_578581bd80c2a672da30fc29" |
| license.payload.product_id | string | yes | See description | [Public App ID](/docs/v1/start/glossary#public-app-id); compare to configured product. | "app_a642cd24641ec976626b" |
| license.payload.product | string | yes | See description | Product display name. | "Docs fixture product" |
| license.payload.plan | string | yes | See description | Product-plan slug. | "fixture-plan" |
| license.payload.status | string | yes | enum=["active", "suspended", "revoked", "expired", "pending", "cancelled"] | Stored license status in lowercase. | "active" |
| license.payload.environment | string | yes | enum=["sandbox", "[live](/docs/v1/start/glossary#live)"] | Bound license environment. | "sandbox" |
| license.payload.expires_at | string or null | yes | format="date-time" | Independent license expiry; null has no configured expiry. | "2026-11-16T10:39:35+00:00" |
| license.payload.license_key_mask | string | yes | See description | Display-only masked key. | "TESTDOCS-••••-••••-HAHH" |
| license.payload.starts_at | string or null | yes | format="date-time" | Configured license start, currently not enforced by server eligibility. | "2026-10-17T10:39:35+00:00" |
| license.payload.created_at | string or null | yes | format="date-time" | Creation timestamp; database-timezone discrepancy is disclosed. | "2026-10-17T12:39:35+00:00" |
| license.payload.max_devices | integer | yes | See description | Concurrent [device](/docs/v1/start/glossary#device) limit. | 2 |
| license.payload.max_activations | integer or null | yes | See description | Cumulative [activation](/docs/v1/start/glossary#activation) cap; null means no configured cap. | 4 |
| license.payload.activation_count | integer | yes | See description | Cumulative consumed activations. | 1 |
| license.payload.min_version | string or null | yes | See description | Optional lower version restriction. | null |
| license.payload.max_version | string or null | yes | See description | Optional upper version restriction. | null |
| license.payload.active_devices | integer | yes | See description | Active count at snapshot time. | 1 |
| license.payload.customer | object | yes | See description | Customer information; personal data, not an authentication credential. | Nested object/array shown in full JSON |
| license.payload.customer.id | string | yes | See description | Customer public identifier. | "cus_d7db5516f8377f89a869e293" |
| license.payload.customer.name | string or null | yes | See description | Optional customer name. | "Synthetic contract customer" |
| license.payload.customer.email | string | yes | See description | Customer email associated with this license. | "contract-6b9f0843f1d3609f@example.invalid" |
| license.payload.customer.company | string or null | yes | See description | Optional company. | null |
| license.payload.customer.country | string or null | yes | See description | Optional country. | null |
| license.payload.product_details | object | yes | See description | Product display metadata. | Nested object/array shown in full JSON |
| license.payload.product_details.id | string | yes | See description | Public App ID. | "app_a642cd24641ec976626b" |
| license.payload.product_details.name | string | yes | See description | Product display name. | "Docs fixture product" |
| license.payload.product_details.platform | string | yes | See description | Lowercase configured product platform. | "desktop" |
| license.payload.plan_details | object | yes | See description | [Product plan](/docs/v1/start/glossary#product-plan), not the [developer](/docs/v1/start/glossary#developer) [platform subscription](/docs/v1/start/glossary#platform-subscription). | Nested object/array shown in full JSON |
| license.payload.plan_details.id | string | yes | See description | Internal product-plan identifier. | "plan_3bf54c099326639ee183661f" |
| license.payload.plan_details.name | string | yes | See description | Plan display name. | "Fixture plan" |
| license.payload.plan_details.slug | string | yes | See description | Plan slug. | "fixture-plan" |
| license.payload.plan_details.billing_type | string | yes | See description | Lowercase product-plan billing type. | "monthly" |
| license.payload.plan_details.price | number | yes | See description | PHP float; preserve numeric tokens such as19.0 for signatures. | 19.5 |
| license.payload.plan_details.currency | string | yes | See description | Configured product-plan currency. | "EUR" |
| license.payload.plan_details.duration_days | integer or null | yes | See description | Configured duration in days. | 30 |
| license.payload.plan_details.trial_days | integer or null | yes | See description | Configured trial duration in days. | null |
| license.payload.features | object or array | yes | See description | Dynamic plan feature JSON values; empty PHP feature array may be[]. Validate types before use. | Nested object/array shown in full JSON |
| license.payload.device | object | yes | See description | Installation binding and descriptions. | Nested object/array shown in full JSON |
| license.payload.device.id | string | yes | See description | Device public identifier. | "dev_299a6753c013047b3ed013de" |
| license.payload.device.installation_hash | string or null | yes | See description | SHA256 of supplied installation ID; null if validation header was omitted. | "e119b615ebfb5e5a2da5ea9c2a64b2117621399ff61d16718d460e0bb919a988" |
| license.payload.device.name | string or null | yes | See description | Optional device label; activation can return an empty string. | "Synthetic local installation" |
| license.payload.device.platform | string or null | yes | See description | Optional platform description. | "test" |
| license.payload.device.app_version | string or null | yes | See description | Optional application version. | "1.0.0" |
| license.payload.server_time | string | yes | format="date-time" | Signed snapshot time in UTC. | "2026-10-17T10:39:35+00:00" |
| license.payload.next_validation_at | string | yes | format="date-time" | server_time plus product interval hours. | "2026-10-18T10:39:35+00:00" |
| license.payload.offline_grace_until | string | yes | format="date-time" | server_time plus grace hours, not added after the [validation interval](/docs/v1/start/glossary#validation-interval). | "2026-10-24T10:39:35+00:00" |
| license.signature | string | yes | pattern="^[A-Za-z0-9_-]{86}$" | Unpadded base64url Ed25519 signature over canonical payload bytes. | "wYwFAPoyaaIVtq8zvUHlQeyqV91sI7115WJHUzY7unDEjOts7MrN_OL3PZAd-Ahd-OdfI-EjIwAVwhfLbYQlDQ" |
| license.algorithm | string | yes | const="Ed25519" | Fixed algorithm, not negotiated. | "Ed25519" |
| license.key_id | string | yes | See description | Must equal independently trusted key ID. | "ed25519_2b9bc7e214b1209f" |
| request_id | string | yes | pattern="^req_[a-f0-9]{24}$" | Request correlation ID. Replay bodies can retain an earlier ID. | "req_b8b3d83f5a1820e7c2f16167" |

### 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? |
| --- | --- | --- | --- | --- |
| 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 |
| INVALID_TOKEN | 401 | Missing/non-act_/unknown/revoked/deactivated activation token | Reactivate eligible installation | No blind retry; apply the correction |
| INVALID_REQUEST | 422 | Input constraints or entitlement/resource/renewal domain rejection | Correct input/plan; not blind retry | No blind retry; apply the correction |
| DEVICE_NOT_AUTHORIZED | 403 | Token is active but associated device is not ACTIVE | Reactivation if eligible | No blind retry; apply the correction |
| DEVICE_MISMATCH | 403 | Provided installation ID does not match token-bound HMAC hash | Use original installation; do not copy token | No blind retry; apply the correction |
| LICENSE_EXPIRED | 403 | Elapsed expires_at before state check; or EXPIRED state; SDK local expiry has no HTTP | Renew eligible license | No blind retry; apply the correction |
| LICENSE_REVOKED | 403 | License REVOKED and no elapsed deadline taking precedence | Do not retry; contact developer | No blind retry; apply the correction |
| LICENSE_SUSPENDED | 403 | License SUSPENDED and no elapsed deadline taking precedence | Restore then reactivate | No blind retry; apply the correction |
| LICENSE_CANCELLED | 403 | License CANCELLED and no elapsed deadline taking precedence | Do not retry; new eligible license | No blind retry; apply the correction |
| LICENSE_PENDING | 403 | License PENDING and no elapsed deadline taking precedence | Wait for authorized activation | 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 |

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
Updates activation.last_validated_at and device.last_seen_at. It does not create a new token, consume another lifetime activation, emit a dedicated validation audit/[webhook](/docs/v1/start/glossary#webhook) or send email. Existing tokens are checked against device/license state. Current validation does not consistently recheck product status/deletion; see the known limitations. An elapsed expiry is rejected, but the attempted EXPIRED update rolls back with the rejection; cron may later persist that state.

Authenticated requests can consume the [organization](/docs/v1/start/glossary#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
Idempotency-Key is ignored. Bounded validation retries are possible after a transport failure, but do not loop after an explicit rejection. Respect signed next_validation_at and the client's verified-cache policy. Omission of X-Installation-ID is transport-accepted and returns a null signed installation_hash; official clients expect a bound hash, so always send the header.

## Rate limits
120 requests per60 seconds for SHA256(IP + activation token). Malformed/missing token or installation headers can reject before the bucket is reached.
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 validate.
### 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 validate.
### 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 validate.
### 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 validate.
### PHP
```php
<?php
declare(strict_types=1);
// Purpose: inspect one Sandbox API operation; not an entitlement verifier.
// Requirements: PHP8.1+, cURL extension. Run: php request.php public-key
// Expected: JSON, exit0 success/1 rejection/2 setup or transport failure.
// Credentials/body via KDP_* variables. Stdout may contain new credentials:
// use a private terminal only, not application/CI logs. Verify signed state separately.
$operations = json_decode(<<<'JSON'
{
  "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"
  }
}
JSON, true, 512, JSON_THROW_ON_ERROR);
function required(string $name): string {
    $value = (string) getenv($name);
    if ($value === '' || str_contains($value, "\r") || str_contains($value, "\n")) throw new RuntimeException('Missing configuration.');
    return $value;
}
try {
    $name = $argv[1] ?? '';
    if ($argc !== 2 || !isset($operations[$name])) throw new RuntimeException('Invalid operation.');
    $operation = $operations[$name];
    $base = rtrim(getenv('KDP_BASE_URL') ?: 'https://licensing.kdpika.com/api/v1', '/');
    $url = parse_url($base);
    $loopback = ($url['scheme'] ?? '') === 'http' && in_array($url['host'] ?? '', ['127.0.0.1', 'localhost'], true) && getenv('KDP_ALLOW_LOOPBACK') === '1';
    if (!$url || empty($url['host']) || (($url['scheme'] ?? '') !== 'https' && !$loopback) || isset($url['user'], $url['pass']) || isset($url['user']) || isset($url['query']) || isset($url['fragment']) || ($url['path'] ?? '') !== '/api/v1') throw new RuntimeException('Invalid base URL.');
    $path = $operation['path'];
    if (str_contains($path, '{license}')) {
        $id = required('KDP_LICENSE_ID');
        if (!preg_match('/^[A-Za-z0-9_-]+$/D', $id)) throw new RuntimeException('Invalid sample license ID.');
        $path = str_replace('{license}', $id, $path);
    }
    $headers = ['Accept: application/json', 'User-Agent: KDPikaDocsExample/1.0 PHP'];
    if ($operation['auth'] === 'developer') {
        $key = required('KDP_API_KEY');
        if (!str_starts_with($key, 'lmp_sandbox_')) throw new RuntimeException('Sandbox key required.');
        $headers[] = 'Authorization: Bearer ' . $key;
    } elseif ($operation['auth'] === 'activation') $headers[] = 'Authorization: Bearer ' . required('KDP_ACTIVATION_TOKEN');
    elseif ($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');
    $curl = curl_init($base . $path);
    $options = [CURLOPT_RETURNTRANSFER => 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 -- validate.
### 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
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup><Compile Remove="errors/**/*.cs" /><None Remove="errors/**/obj/**;errors/**/bin/**" /></ItemGroup>
</Project>
```

Run node compiled/request.js validate.
### TypeScript
```typescript
// Purpose: inspect one Sandbox API operation; not an entitlement verifier.
// Requirements: TypeScript7.0.2, @types/node22.19.7, Node18.20+ native fetch, trusted server/Electron main process.
// Run compiled request.js with public-key after strict TypeScript compilation. 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: Readonly<Record<string, {method:string;path:string;auth:string}>> = Object.freeze({
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
});
function required(name: string): string {
  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: Record<string,string> = {'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 java -cp .:gson.jar Request validate.
### Java
```java
// Purpose: inspect one client-callable Sandbox operation, not grant feature access.
// Requires Java17+, Gson2.14.0. Run: java -cp .:gson.jar Request public-key
// Windows classpaths use semicolons. Expected: JSON; exit0 success/1 API error/2 setup or transport.
// Credentials/body: KDP_* environment variables. Private terminal only; output may contain secrets.
import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import com.google.gson.*;

public final class Request {
    static final String CONTRACT = """
{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}
""";
    static String required(String name) {
        String value = System.getenv(name);
        if (value == null || value.isEmpty() || value.contains("\r") || value.contains("\n")) throw new IllegalArgumentException("Missing configuration.");
        return value;
    }
    public static void main(String[] args) {
        try {
            JsonObject operations = JsonParser.parseString(CONTRACT).getAsJsonObject();
            if (args.length != 1 || !operations.has(args[0])) throw new IllegalArgumentException("Unknown operation.");
            String name = args[0]; JsonObject op = operations.getAsJsonObject(name);
            String base = System.getenv().getOrDefault("KDP_BASE_URL", "https://licensing.kdpika.com/api/v1").replaceAll("/+$", "");
            URI uri = URI.create(base);
            boolean local = "http".equals(uri.getScheme()) && ("localhost".equals(uri.getHost()) || "127.0.0.1".equals(uri.getHost())) && "1".equals(System.getenv("KDP_ALLOW_LOOPBACK"));
            if (uri.getHost() == null || (!"https".equals(uri.getScheme()) && !local) || uri.getUserInfo() != null || uri.getQuery() != null || uri.getFragment() != null || !"/api/v1".equals(uri.getPath())) throw new IllegalArgumentException("Invalid base URL.");
            HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(base + op.get("path").getAsString())).timeout(Duration.ofSeconds(15))
                .header("Accept", "application/json").header("User-Agent", "KDPikaDocsExample/1.0 Java");
            String auth = op.get("auth").getAsString();
            if (auth.equals("publicApp")) request.header("X-App-ID", required("KDP_APP_ID")).header("X-Environment", "SANDBOX");
            if (auth.equals("activation")) request.header("Authorization", "Bearer " + required("KDP_ACTIVATION_TOKEN"));
            if (name.equals("validate")) request.header("X-Installation-ID", required("KDP_INSTALLATION_ID"));
            if (op.get("method").getAsString().equals("POST")) {
                String body = System.getenv().getOrDefault("KDP_BODY_JSON", "{}");
                if (!JsonParser.parseString(body).isJsonObject()) throw new IllegalArgumentException("JSON object required.");
                request.header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8));
            } else request.GET();
            HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).followRedirects(HttpClient.Redirect.NEVER).build();
            HttpResponse<String> response = client.send(request.build(), HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
            JsonObject result = JsonParser.parseString(response.body()).getAsJsonObject();
            System.out.write(response.body().getBytes(StandardCharsets.UTF_8)); System.out.write(10);
            if (response.statusCode() < 200 || response.statusCode() >= 300 || !result.has("success") || !result.get("success").equals(new JsonPrimitive(true))) {
                System.err.println("API rejection. Inspect error.code/request_id; reconcile mutations before retrying."); System.exit(1);
            }
        } catch (Exception error) {
            System.err.println("Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations."); System.exit(2);
        }
    }
}
```

Run go run request.go validate.
### Go
```go
// Purpose: inspect one client-callable Sandbox operation, not grant access.
// Requires Go1.20+ standard library. Run: go run request.go public-key
// Expected: JSON, exit0 success/1 API rejection/2 setup or transport failure.
// Credentials/body: KDP_* variables; output may contain secrets. Private terminal only.
package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"strings"
	"time"
)

type operation struct {
	Method string `json:"method"`
	Path   string `json:"path"`
	Auth   string `json:"auth"`
}

const contract = `{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}`

func required(name string) string {
	v := os.Getenv(name)
	if v == "" || strings.ContainsAny(v, "\r\n") {
		panic("configuration")
	}
	return v
}
func execute() int {
	var operations map[string]operation
	if json.Unmarshal([]byte(contract), &operations) != nil || len(os.Args) != 2 {
		panic("operation")
	}
	name := os.Args[1]
	op, ok := operations[name]
	if !ok {
		panic("operation")
	}
	base := os.Getenv("KDP_BASE_URL")
	if base == "" {
		base = "https://licensing.kdpika.com/api/v1"
	}
	base = strings.TrimRight(base, "/")
	u, err := url.Parse(base)
	if err != nil {
		panic("URL")
	}
	local := u.Scheme == "http" && (u.Hostname() == "127.0.0.1" || u.Hostname() == "localhost") && os.Getenv("KDP_ALLOW_LOOPBACK") == "1"
	if u.Hostname() == "" || (u.Scheme != "https" && !local) || u.User != nil || u.RawQuery != "" || u.Fragment != "" || u.Path != "/api/v1" {
		panic("URL")
	}
	body := ""
	if op.Method == "POST" {
		body = os.Getenv("KDP_BODY_JSON")
		if body == "" {
			body = "{}"
		}
		var object map[string]json.RawMessage
		if json.Unmarshal([]byte(body), &object) != nil || object == nil {
			panic("body")
		}
	}
	request, err := http.NewRequest(op.Method, base+op.Path, strings.NewReader(body))
	if err != nil {
		panic("request")
	}
	request.Header.Set("Accept", "application/json")
	request.Header.Set("User-Agent", "KDPikaDocsExample/1.0 Go")
	if op.Method == "POST" {
		request.Header.Set("Content-Type", "application/json")
	}
	if op.Auth == "publicApp" {
		request.Header.Set("X-App-ID", required("KDP_APP_ID"))
		request.Header.Set("X-Environment", "SANDBOX")
	}
	if op.Auth == "activation" {
		request.Header.Set("Authorization", "Bearer "+required("KDP_ACTIVATION_TOKEN"))
	}
	if name == "validate" {
		request.Header.Set("X-Installation-ID", required("KDP_INSTALLATION_ID"))
	}
	client := &http.Client{Timeout: 15 * time.Second, CheckRedirect: func(_ *http.Request, _ []*http.Request) error { return http.ErrUseLastResponse }}
	response, err := client.Do(request)
	if err != nil {
		panic("transport")
	}
	defer response.Body.Close()
	raw, err := io.ReadAll(io.LimitReader(response.Body, 1048577))
	if err != nil || len(raw) > 1048576 {
		panic("response")
	}
	var result struct {
		Success bool `json:"success"`
	}
	if json.Unmarshal(raw, &result) != nil {
		panic("JSON")
	}
	fmt.Println(string(raw))
	if response.StatusCode < 200 || response.StatusCode >= 300 || !result.Success {
		fmt.Fprintln(os.Stderr, "API rejection. Inspect error.code/request_id; reconcile mutations before retrying.")
		return 1
	}
	return 0
}
func main() {
	code := 2
	func() {
		defer func() {
			if recover() != nil {
				fmt.Fprintln(os.Stderr, "Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.")
			}
		}()
		code = execute()
	}()
	os.Exit(code)
}
```

Run cargo run --locked --manifest-path rust/Cargo.toml -- validate.
### Rust
```rust
// Purpose: inspect one client-callable Sandbox operation; not entitlement verification.
// Requires Rust1.82+, pinned Cargo.toml/Cargo.lock. Run: cargo run -- public-key
// Expected: raw JSON; exit0 success/1 API rejection/2 setup or transport failure.
// KDP_* variables carry credentials/body; private terminal only, output may contain secrets.
use serde_json::Value;
use std::{env, process, time::Duration};
const CONTRACT: &str = r#"{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}"#;
fn required(name: &str) -> Result<String, Box<dyn std::error::Error>> {
    let value = env::var(name)?;
    if value.is_empty() || value.contains('\r') || value.contains('\n') {
        return Err("configuration".into());
    };
    Ok(value)
}
fn execute() -> Result<i32, Box<dyn std::error::Error>> {
    let operations: Value = serde_json::from_str(CONTRACT)?;
    let args: Vec<String> = env::args().collect();
    if args.len() != 2 {
        return Err("operation".into());
    }
    let name = &args[1];
    let op = operations.get(name).ok_or("operation")?;
    let base = env::var("KDP_BASE_URL")
        .unwrap_or_else(|_| "https://licensing.kdpika.com/api/v1".into())
        .trim_end_matches('/')
        .to_string();
    let uri = url::Url::parse(&base)?;
    let local = uri.scheme() == "http"
        && matches!(uri.host_str(), Some("127.0.0.1" | "localhost"))
        && env::var("KDP_ALLOW_LOOPBACK").unwrap_or_default() == "1";
    if uri.host_str().is_none()
        || (uri.scheme() != "https" && !local)
        || !uri.username().is_empty()
        || uri.password().is_some()
        || uri.query().is_some()
        || uri.fragment().is_some()
        || uri.path() != "/api/v1"
    {
        return Err("URL".into());
    }
    let method = op["method"].as_str().ok_or("method")?;
    let agent = ureq::AgentBuilder::new()
        .timeout(Duration::from_secs(15))
        .redirects(0)
        .build();
    let target = base + op["path"].as_str().ok_or("path")?;
    let mut request = agent
        .request(method, &target)
        .set("Accept", "application/json")
        .set("User-Agent", "KDPikaDocsExample/1.0 Rust");
    if op["auth"] == "publicApp" {
        request = request
            .set("X-App-ID", &required("KDP_APP_ID")?)
            .set("X-Environment", "SANDBOX")
    }
    if op["auth"] == "activation" {
        request = request.set(
            "Authorization",
            &("Bearer ".to_string() + &required("KDP_ACTIVATION_TOKEN")?),
        )
    }
    if name == "validate" {
        request = request.set("X-Installation-ID", &required("KDP_INSTALLATION_ID")?)
    }
    let answer = if method == "POST" {
        let body = env::var("KDP_BODY_JSON").unwrap_or_else(|_| "{}".into());
        if !serde_json::from_str::<Value>(&body)?.is_object() {
            return Err("body".into());
        }
        request
            .set("Content-Type", "application/json")
            .send_string(&body)
    } else {
        request.call()
    };
    let response = match answer {
        Ok(response) => response,
        Err(ureq::Error::Status(_, response)) => response,
        Err(error) => return Err(Box::new(error)),
    };
    let status = response.status();
    let raw = response.into_string()?;
    let result: Value = serde_json::from_str(&raw)?;
    println!("{}", raw);
    if !(200..300).contains(&status) || result["success"] != true {
        eprintln!(
            "API rejection. Inspect error.code/request_id; reconcile mutations before retrying."
        );
        return Ok(1);
    }
    Ok(0)
}
fn main() {
    process::exit(match execute() {
        Ok(code) => code,
        Err(_) => {
            eprintln!("Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.");
            2
        }
    })
}
```
```rust
[package]
name = "kdpika-api-example"
version = "1.0.0"
edition = "2021"
rust-version = "1.82"

[dependencies]
ureq = { version = "=2.12.1", default-features = false, features = ["tls"] }
url = "=2.5.2"
serde_json = "=1.0.145"
# Keep the tested Rust1.82 toolchain compatible with this pinned lock.
zeroize = "=1.8.1"
```

Run ruby request.rb validate.
### Ruby
```ruby
# Purpose: inspect one client-callable Sandbox operation, not grant feature access.
# Requires Ruby2.6+ standard library. Run: ruby request.rb public-key
# Expected: JSON; exit0 success/1 API rejection/2 setup or transport failure.
# Credentials/body: KDP_* variables. Private terminal only; output may contain secrets.
require 'json'
require 'net/http'
require 'uri'
require 'openssl'
STDOUT.set_encoding(Encoding::UTF_8)
OPERATIONS = JSON.parse(<<~'JSON')
{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}
JSON
def required(name)
  value = ENV.fetch(name, '')
  raise 'configuration' if value.empty? || value.match?(/[\r\n]/)
  value
end
begin
  raise 'operation' unless ARGV.length == 1 && OPERATIONS.key?(ARGV[0])
  name = ARGV[0]; op = OPERATIONS.fetch(name)
  base = ENV.fetch('KDP_BASE_URL', 'https://licensing.kdpika.com/api/v1').sub(%r{/+$}, '')
  uri = URI.parse(base)
  local = uri.scheme == 'http' && ['127.0.0.1','localhost'].include?(uri.host) && ENV['KDP_ALLOW_LOOPBACK'] == '1'
  raise 'URL' unless uri.host && (uri.scheme == 'https' || local) && !uri.userinfo && !uri.query && !uri.fragment && uri.path == '/api/v1'
  target = URI.parse(base + op.fetch('path'))
  request = op.fetch('method') == 'GET' ? Net::HTTP::Get.new(target) : Net::HTTP::Post.new(target)
  request['Accept'] = 'application/json'; request['User-Agent'] = 'KDPikaDocsExample/1.0 Ruby'
  if op['auth'] == 'publicApp'
    request['X-App-ID'] = required('KDP_APP_ID'); request['X-Environment'] = 'SANDBOX'
  elsif op['auth'] == 'activation'
    request['Authorization'] = 'Bearer ' + required('KDP_ACTIVATION_TOKEN')
  end
  request['X-Installation-ID'] = required('KDP_INSTALLATION_ID') if name == 'validate'
  if op['method'] == 'POST'
    body = ENV.fetch('KDP_BODY_JSON', '{}'); raise 'JSON object' unless JSON.parse(body).is_a?(Hash)
    request['Content-Type'] = 'application/json'; request.body = body
  end
  http = Net::HTTP.new(target.host, target.port, nil)
  http.use_ssl = target.scheme == 'https'; http.verify_mode = OpenSSL::SSL::VERIFY_PEER
  http.open_timeout = 5; http.read_timeout = 15
  response = http.request(request) # Net::HTTP does not follow redirects.
  result = JSON.parse(response.body)
  puts response.body
  unless response.code.to_i.between?(200,299) && result['success'] == true
    warn 'API rejection. Inspect error.code/request_id; reconcile mutations before retrying.'; exit 1
  end
rescue StandardError
  warn 'Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.'; exit 2
end
```

Run java -cp request.jar:gson.jar RequestKt validate.
### Kotlin
```kotlin
// Purpose: inspect one client-callable Sandbox operation; not an entitlement verifier.
// Requires Kotlin2.4.21/JVM17+, Gson2.14.0. Run compiled RequestKt with public-key.
// Expected: raw JSON; exit0 success/1 API rejection/2 setup or transport failure.
// KDP_* variables carry credentials/body; private terminal only, never application/CI logs.
import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.time.Duration
import com.google.gson.JsonParser
import com.google.gson.JsonPrimitive
import kotlin.system.exitProcess

val operationsJson = """
{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}
""".trimIndent()
fun required(name: String): String = (System.getenv(name) ?: "").also {
    require(it.isNotEmpty() && !it.contains('\r') && !it.contains('\n')) { "Missing configuration." }
}
fun main(args: Array<String>) {
    try {
        val operations = JsonParser.parseString(operationsJson).asJsonObject
        require(args.size == 1 && operations.has(args[0]))
        val name = args[0]; val op = operations.getAsJsonObject(name)
        val base = (System.getenv("KDP_BASE_URL") ?: "https://licensing.kdpika.com/api/v1").trimEnd('/')
        val uri = URI.create(base)
        val local = uri.scheme == "http" && uri.host in listOf("localhost", "127.0.0.1") && System.getenv("KDP_ALLOW_LOOPBACK") == "1"
        require(uri.host != null && (uri.scheme == "https" || local) && uri.userInfo == null && uri.query == null && uri.fragment == null && uri.path == "/api/v1")
        val request = HttpRequest.newBuilder(URI.create(base + op["path"].asString)).timeout(Duration.ofSeconds(15))
            .header("Accept", "application/json").header("User-Agent", "KDPikaDocsExample/1.0 Kotlin")
        when (op["auth"].asString) {
            "publicApp" -> request.header("X-App-ID", required("KDP_APP_ID")).header("X-Environment", "SANDBOX")
            "activation" -> request.header("Authorization", "Bearer " + required("KDP_ACTIVATION_TOKEN"))
        }
        if (name == "validate") request.header("X-Installation-ID", required("KDP_INSTALLATION_ID"))
        if (op["method"].asString == "POST") {
            val body = System.getenv("KDP_BODY_JSON") ?: "{}"
            require(JsonParser.parseString(body).isJsonObject)
            request.header("Content-Type", "application/json").POST(HttpRequest.BodyPublishers.ofString(body))
        } else request.GET()
        val client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).followRedirects(HttpClient.Redirect.NEVER).build()
        val response = client.send(request.build(), HttpResponse.BodyHandlers.ofString())
        val result = JsonParser.parseString(response.body()).asJsonObject
        System.out.write(response.body().toByteArray(Charsets.UTF_8)); System.out.write(10)
        if (response.statusCode() !in 200..299 || result["success"] != JsonPrimitive(true)) {
            System.err.println("API rejection. Inspect error.code/request_id; reconcile mutations before retrying."); exitProcess(1)
        }
    } catch (error: Exception) {
        System.err.println("Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations."); exitProcess(2)
    }
}
```

Run ./request validate.
### Swift
```swift
// Purpose: inspect one client-callable Sandbox operation, not grant feature access.
// Requires Swift5.7+, Foundation; FoundationNetworking on Linux.
// Build: swiftc -parse-as-library request.swift -o request; run: ./request public-key
// Expected: JSON; exit0 success/1 API rejection/2 setup or transport failure.
// Credentials/body: KDP_* variables. Private terminal only; output may contain secrets.
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif
let contract = #"""
{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}
"""#
enum SetupError: Error {case invalid}
func required(_ name:String) throws -> String {
    let value=ProcessInfo.processInfo.environment[name] ?? ""
    guard !value.isEmpty && !value.contains("\r") && !value.contains("\n") else {throw SetupError.invalid};return value
}
final class NoRedirect: NSObject, URLSessionTaskDelegate, @unchecked Sendable {
    func urlSession(_ session:URLSession,task:URLSessionTask,willPerformHTTPRedirection response:HTTPURLResponse,newRequest request:URLRequest,completionHandler:@escaping(URLRequest?)->Void){completionHandler(nil)}
}
@main struct Example {
    static func main() async {
        do {
            let env=ProcessInfo.processInfo.environment
            let operations=try JSONSerialization.jsonObject(with:Data(contract.utf8)) as! [String:[String:String]]
            guard CommandLine.arguments.count==2,let op=operations[CommandLine.arguments[1]] else {throw SetupError.invalid}
            let name=CommandLine.arguments[1]
            let base=(env["KDP_BASE_URL"] ?? "https://licensing.kdpika.com/api/v1").replacingOccurrences(of:"/+$",with:"",options:.regularExpression)
            guard let parts=URLComponents(string:base),let host=parts.host else {throw SetupError.invalid}
            let local=parts.scheme=="http" && ["localhost","127.0.0.1"].contains(host) && env["KDP_ALLOW_LOOPBACK"]=="1"
            guard (parts.scheme=="https" || local) && parts.user==nil && parts.password==nil && parts.query==nil && parts.fragment==nil && parts.path=="/api/v1",let url=URL(string:base+op["path"]!) else {throw SetupError.invalid}
            var request=URLRequest(url:url);request.httpMethod=op["method"];request.timeoutInterval=15
            request.setValue("application/json",forHTTPHeaderField:"Accept");request.setValue("KDPikaDocsExample/1.0 Swift",forHTTPHeaderField:"User-Agent")
            if op["auth"]=="publicApp" {request.setValue(try required("KDP_APP_ID"),forHTTPHeaderField:"X-App-ID");request.setValue("SANDBOX",forHTTPHeaderField:"X-Environment")}
            if op["auth"]=="activation" {request.setValue("Bearer "+(try required("KDP_ACTIVATION_TOKEN")),forHTTPHeaderField:"Authorization")}
            if name=="validate" {request.setValue(try required("KDP_INSTALLATION_ID"),forHTTPHeaderField:"X-Installation-ID")}
            if op["method"]=="POST" {
                let body=Data((env["KDP_BODY_JSON"] ?? "{}").utf8)
                guard try JSONSerialization.jsonObject(with:body) is [String:Any] else {throw SetupError.invalid}
                request.httpBody=body;request.setValue("application/json",forHTTPHeaderField:"Content-Type")
            }
            let session=URLSession(configuration:.ephemeral,delegate:NoRedirect(),delegateQueue:nil)
            defer {session.invalidateAndCancel()}
            let (raw,response)=try await session.data(for:request)
            guard let http=response as? HTTPURLResponse,let result=try JSONSerialization.jsonObject(with:raw) as? [String:Any],let text=String(data:raw,encoding:.utf8) else {throw SetupError.invalid}
            _ = text // Decoding above checks UTF-8 without reserializing JSON.
            FileHandle.standardOutput.write(raw);FileHandle.standardOutput.write(Data([10]))
            guard (200..<300).contains(http.statusCode),result["success"] as? Bool == true else {
                FileHandle.standardError.write(Data("API rejection. Inspect error.code/request_id; reconcile mutations before retrying.\n".utf8));exit(1)
            }
        } catch {
            FileHandle.standardError.write(Data("Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.\n".utf8));exit(2)
        }
    }
}
```

Run dart run request.dart validate.
### Dart
```dart
// Purpose: inspect one client-callable Sandbox operation, not grant feature access.
// Requires Dart3.7+ standard library. Run: dart run request.dart public-key
// Expected: JSON; exit0 success/1 API rejection/2 setup or transport failure.
// KDP_* variables carry credentials/body. Private terminal only; output can contain secrets.
import 'dart:convert';
import 'dart:io';

const contract = r'''{
  "public-key": {
    "method": "GET",
    "path": "/public-key",
    "auth": "public"
  },
  "activate": {
    "method": "POST",
    "path": "/licenses/activate",
    "auth": "publicApp"
  },
  "validate": {
    "method": "POST",
    "path": "/licenses/validate",
    "auth": "activation"
  },
  "deactivate": {
    "method": "POST",
    "path": "/licenses/deactivate",
    "auth": "activation"
  }
}''';
String required(String name) {
  final value = Platform.environment[name] ?? '';
  if (value.isEmpty || value.contains('\r') || value.contains('\n'))
    throw StateError('configuration');
  return value;
}

Future<void> main(List<String> args) async {
  stdout.encoding = utf8;
  final client = HttpClient()..connectionTimeout = const Duration(seconds: 5);
  try {
    final operations = jsonDecode(contract) as Map<String, dynamic>;
    if (args.length != 1 || !operations.containsKey(args[0]))
      throw StateError('operation');
    final name = args[0];
    final op = operations[name] as Map<String, dynamic>;
    final base =
        (Platform.environment['KDP_BASE_URL'] ??
                'https://licensing.kdpika.com/api/v1')
            .replaceFirst(RegExp(r'/+$'), '');
    final uri = Uri.parse(base);
    final local =
        uri.scheme == 'http' &&
        ['127.0.0.1', 'localhost'].contains(uri.host) &&
        Platform.environment['KDP_ALLOW_LOOPBACK'] == '1';
    if (uri.host.isEmpty ||
        (uri.scheme != 'https' && !local) ||
        uri.userInfo.isNotEmpty ||
        uri.hasQuery ||
        uri.hasFragment ||
        uri.path != '/api/v1')
      throw StateError('URL');
    final request = await client
        .openUrl(
          op['method'] as String,
          Uri.parse(base + (op['path'] as String)),
        )
        .timeout(const Duration(seconds: 15));
    request.followRedirects = false;
    request.headers.set('Accept', 'application/json');
    request.headers.set('User-Agent', 'KDPikaDocsExample/1.0 Dart');
    if (op['auth'] == 'publicApp') {
      request.headers.set('X-App-ID', required('KDP_APP_ID'));
      request.headers.set('X-Environment', 'SANDBOX');
    }
    if (op['auth'] == 'activation')
      request.headers.set(
        'Authorization',
        'Bearer ${required('KDP_ACTIVATION_TOKEN')}',
      );
    if (name == 'validate')
      request.headers.set('X-Installation-ID', required('KDP_INSTALLATION_ID'));
    if (op['method'] == 'POST') {
      final body = Platform.environment['KDP_BODY_JSON'] ?? '{}';
      if (jsonDecode(body) is! Map) throw StateError('JSON object');
      request.headers.set('Content-Type', 'application/json');
      request.add(utf8.encode(body));
    }
    final response = await request.close().timeout(const Duration(seconds: 15));
    final raw = await utf8.decoder
        .bind(response)
        .join()
        .timeout(const Duration(seconds: 15));
    final result = jsonDecode(raw) as Map<String, dynamic>;
    stdout.writeln(raw);
    if (response.statusCode < 200 ||
        response.statusCode >= 300 ||
        result['success'] != true) {
      stderr.writeln(
        'API rejection. Inspect error.code/request_id; reconcile mutations before retrying.',
      );
      exitCode = 1;
    }
  } catch (error) {
    stderr.writeln(
      'Request unavailable or configuration invalid. Check KDP_* settings/connectivity; do not blindly retry mutations.',
    );
    exitCode = 2;
  } finally {
    client.close(force: true);
  }
}
```

Run ./request-c validate.
### C
```c
/* C11 entry point. Build with client_http.c include, yyjson0.13.0 and libcurl7.76+.
 * Run request public-key; expected JSON, exit0 success/1 rejection/2 unavailable. */
#include "client_http.c"
int main(int argc,char **argv){return kdpika_example_main(argc,argv);}
```
```c
/* Purpose: shared native libcurl transport for C11 and C++17 Sandbox examples.
 * Requires libcurl7.76+, yyjson0.13.0. Build commands are in the sample README.
 * Run request public-key. JSON stdout; exit0 success/1 rejection/2 setup/transport.
 * Credentials/body: KDP_* environment. Private terminal only; output may contain secrets.
 * Transport inspection only: verify signed state and policy before authorizing access.
 */
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <curl/curl.h>
#include "yyjson.h"
static const char *kdp_contract="{\"public-key\":{\"method\":\"GET\",\"path\":\"/public-key\",\"auth\":\"public\"},\"activate\":{\"method\":\"POST\",\"path\":\"/licenses/activate\",\"auth\":\"publicApp\"},\"validate\":{\"method\":\"POST\",\"path\":\"/licenses/validate\",\"auth\":\"activation\"},\"deactivate\":{\"method\":\"POST\",\"path\":\"/licenses/deactivate\",\"auth\":\"activation\"}}";
typedef struct {char *data;size_t size;} kdp_buffer;
static size_t kdp_receive(char *data,size_t size,size_t count,void *context){
    kdp_buffer *b=(kdp_buffer *)context;
    if(size && count>SIZE_MAX/size)return 0;
    size_t n=size*count;if(n>1048576-b->size)return 0;
    char *p=(char *)realloc(b->data,b->size+n+1);if(!p)return 0;
    b->data=p;memcpy(p+b->size,data,n);b->size+=n;p[b->size]=0;return n;
}
static const char *kdp_env(const char *name){const char *v=getenv(name);return v?v:"";}
static const char *kdp_required(const char *name){const char *v=kdp_env(name);return *v&&!strchr(v,'\r')&&!strchr(v,'\n')?v:NULL;}
static int kdp_header(struct curl_slist **headers,const char *name,const char *value){
    if(!value)return 0;size_t n=strlen(name)+strlen(value)+3;char *line=(char *)malloc(n);if(!line)return 0;
    snprintf(line,n,"%s: %s",name,value);struct curl_slist *next=curl_slist_append(*headers,line);free(line);
    if(!next)return 0;*headers=next;return 1;
}
static int kdpika_example_main(int argc,char **argv){
    int code=2;CURL *curl=NULL;CURLU *url=NULL;struct curl_slist *headers=NULL;
    yyjson_doc *ops=NULL,*bodydoc=NULL,*result=NULL;char *scheme=NULL,*host=NULL,*path=NULL,*part=NULL,*target=NULL;
    kdp_buffer buffer={NULL,0};const char *base=kdp_env("KDP_BASE_URL"),*body=kdp_env("KDP_BODY_JSON");
    const char *method=NULL,*route=NULL,*auth=NULL;yyjson_val *op=NULL;long status=0;
    if(argc!=2)goto cleanup;
    if(!*base)base="https://licensing.kdpika.com/api/v1";
    if(!*body)body="{}";
    ops=yyjson_read(kdp_contract,strlen(kdp_contract),0);if(!ops)goto cleanup;
    op=yyjson_obj_get(yyjson_doc_get_root(ops),argv[1]);if(!op)goto cleanup;
    method=yyjson_get_str(yyjson_obj_get(op,"method"));route=yyjson_get_str(yyjson_obj_get(op,"path"));auth=yyjson_get_str(yyjson_obj_get(op,"auth"));
    if(!method||!route||!auth||curl_global_init(CURL_GLOBAL_DEFAULT)!=0)goto cleanup;
    url=curl_url();if(!url||curl_url_set(url,CURLUPART_URL,base,0)!=CURLUE_OK)goto cleanup;
    if(curl_url_get(url,CURLUPART_SCHEME,&scheme,0)||curl_url_get(url,CURLUPART_HOST,&host,0)||curl_url_get(url,CURLUPART_PATH,&path,0))goto cleanup;
    if(strcmp(path,"/api/v1")!=0)goto cleanup;
    if(strcmp(scheme,"https")!=0 && !(strcmp(scheme,"http")==0 && (!strcmp(host,"localhost")||!strcmp(host,"127.0.0.1")) && !strcmp(kdp_env("KDP_ALLOW_LOOPBACK"),"1")))goto cleanup;
    {CURLUPart forbidden[]={CURLUPART_USER,CURLUPART_PASSWORD,CURLUPART_QUERY,CURLUPART_FRAGMENT};
    for(size_t i=0;i<sizeof(forbidden)/sizeof(forbidden[0]);i++){if(curl_url_get(url,forbidden[i],&part,0)==CURLUE_OK)goto cleanup;}}
    target=(char *)malloc(strlen(base)+strlen(route)+1);if(!target)goto cleanup;strcpy(target,base);strcat(target,route);
    if(!kdp_header(&headers,"Accept","application/json")||!kdp_header(&headers,"User-Agent","KDPikaDocsExample/1.0 Native"))goto cleanup;
    if(!strcmp(auth,"publicApp")&&(!kdp_header(&headers,"X-App-ID",kdp_required("KDP_APP_ID"))||!kdp_header(&headers,"X-Environment","SANDBOX")))goto cleanup;
    if(!strcmp(auth,"activation")){
        const char *token=kdp_required("KDP_ACTIVATION_TOKEN");if(!token)goto cleanup;
        char *bearer=(char *)malloc(strlen(token)+8);if(!bearer)goto cleanup;strcpy(bearer,"Bearer ");strcat(bearer,token);
        int ok=kdp_header(&headers,"Authorization",bearer);free(bearer);if(!ok)goto cleanup;
    }
    if(!strcmp(argv[1],"validate")&&!kdp_header(&headers,"X-Installation-ID",kdp_required("KDP_INSTALLATION_ID")))goto cleanup;
    curl=curl_easy_init();if(!curl)goto cleanup;
    curl_easy_setopt(curl,CURLOPT_URL,target);curl_easy_setopt(curl,CURLOPT_CUSTOMREQUEST,method);
    curl_easy_setopt(curl,CURLOPT_FOLLOWLOCATION,0L);curl_easy_setopt(curl,CURLOPT_CONNECTTIMEOUT,5L);curl_easy_setopt(curl,CURLOPT_TIMEOUT,15L);
    curl_easy_setopt(curl,CURLOPT_SSL_VERIFYPEER,1L);curl_easy_setopt(curl,CURLOPT_SSL_VERIFYHOST,2L);
    curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,kdp_receive);curl_easy_setopt(curl,CURLOPT_WRITEDATA,&buffer);
    if(!strcmp(method,"POST")){
        bodydoc=yyjson_read(body,strlen(body),0);if(!bodydoc||!yyjson_is_obj(yyjson_doc_get_root(bodydoc)))goto cleanup;
        if(!kdp_header(&headers,"Content-Type","application/json"))goto cleanup;
        curl_easy_setopt(curl,CURLOPT_POSTFIELDS,body);
    }
    curl_easy_setopt(curl,CURLOPT_HTTPHEADER,headers);if(curl_easy_perform(curl)!=CURLE_OK)goto cleanup;
    curl_easy_getinfo(curl,CURLINFO_RESPONSE_CODE,&status);
    result=yyjson_read(buffer.data,buffer.size,0);if(!result||!yyjson_is_obj(yyjson_doc_get_root(result)))goto cleanup;
    printf("%s\n",buffer.data);
    code=status>=200&&status<300&&yyjson_is_true(yyjson_obj_get(yyjson_doc_get_root(result),"success"))?0:1;
cleanup:
    if(code)fprintf(stderr,"Request rejected, unavailable or configuration invalid. Inspect JSON error.code/request_id when returned; do not blindly retry mutations.\n");
    if(curl)curl_easy_cleanup(curl);if(url)curl_url_cleanup(url);curl_slist_free_all(headers);
    curl_free(scheme);curl_free(host);curl_free(path);curl_free(part);free(target);free(buffer.data);
    yyjson_doc_free(ops);yyjson_doc_free(bodydoc);yyjson_doc_free(result);return code;
}
```

Run ./request-cpp validate.
### C++
```cpp
// C++17 entry point using the complete adjacent native transport.
// Requires yyjson0.13.0 and libcurl7.76+. Run request public-key; JSON/exit0,1,2.
#include "client_http.c"
int main(int argc,char **argv){return kdpika_example_main(argc,argv);}
```
```cpp
/* Purpose: shared native libcurl transport for C11 and C++17 Sandbox examples.
 * Requires libcurl7.76+, yyjson0.13.0. Build commands are in the sample README.
 * Run request public-key. JSON stdout; exit0 success/1 rejection/2 setup/transport.
 * Credentials/body: KDP_* environment. Private terminal only; output may contain secrets.
 * Transport inspection only: verify signed state and policy before authorizing access.
 */
#include <stdio.h>
#include <stdlib.h>
#include <stdint.h>
#include <string.h>
#include <curl/curl.h>
#include "yyjson.h"
static const char *kdp_contract="{\"public-key\":{\"method\":\"GET\",\"path\":\"/public-key\",\"auth\":\"public\"},\"activate\":{\"method\":\"POST\",\"path\":\"/licenses/activate\",\"auth\":\"publicApp\"},\"validate\":{\"method\":\"POST\",\"path\":\"/licenses/validate\",\"auth\":\"activation\"},\"deactivate\":{\"method\":\"POST\",\"path\":\"/licenses/deactivate\",\"auth\":\"activation\"}}";
typedef struct {char *data;size_t size;} kdp_buffer;
static size_t kdp_receive(char *data,size_t size,size_t count,void *context){
    kdp_buffer *b=(kdp_buffer *)context;
    if(size && count>SIZE_MAX/size)return 0;
    size_t n=size*count;if(n>1048576-b->size)return 0;
    char *p=(char *)realloc(b->data,b->size+n+1);if(!p)return 0;
    b->data=p;memcpy(p+b->size,data,n);b->size+=n;p[b->size]=0;return n;
}
static const char *kdp_env(const char *name){const char *v=getenv(name);return v?v:"";}
static const char *kdp_required(const char *name){const char *v=kdp_env(name);return *v&&!strchr(v,'\r')&&!strchr(v,'\n')?v:NULL;}
static int kdp_header(struct curl_slist **headers,const char *name,const char *value){
    if(!value)return 0;size_t n=strlen(name)+strlen(value)+3;char *line=(char *)malloc(n);if(!line)return 0;
    snprintf(line,n,"%s: %s",name,value);struct curl_slist *next=curl_slist_append(*headers,line);free(line);
    if(!next)return 0;*headers=next;return 1;
}
static int kdpika_example_main(int argc,char **argv){
    int code=2;CURL *curl=NULL;CURLU *url=NULL;struct curl_slist *headers=NULL;
    yyjson_doc *ops=NULL,*bodydoc=NULL,*result=NULL;char *scheme=NULL,*host=NULL,*path=NULL,*part=NULL,*target=NULL;
    kdp_buffer buffer={NULL,0};const char *base=kdp_env("KDP_BASE_URL"),*body=kdp_env("KDP_BODY_JSON");
    const char *method=NULL,*route=NULL,*auth=NULL;yyjson_val *op=NULL;long status=0;
    if(argc!=2)goto cleanup;
    if(!*base)base="https://licensing.kdpika.com/api/v1";
    if(!*body)body="{}";
    ops=yyjson_read(kdp_contract,strlen(kdp_contract),0);if(!ops)goto cleanup;
    op=yyjson_obj_get(yyjson_doc_get_root(ops),argv[1]);if(!op)goto cleanup;
    method=yyjson_get_str(yyjson_obj_get(op,"method"));route=yyjson_get_str(yyjson_obj_get(op,"path"));auth=yyjson_get_str(yyjson_obj_get(op,"auth"));
    if(!method||!route||!auth||curl_global_init(CURL_GLOBAL_DEFAULT)!=0)goto cleanup;
    url=curl_url();if(!url||curl_url_set(url,CURLUPART_URL,base,0)!=CURLUE_OK)goto cleanup;
    if(curl_url_get(url,CURLUPART_SCHEME,&scheme,0)||curl_url_get(url,CURLUPART_HOST,&host,0)||curl_url_get(url,CURLUPART_PATH,&path,0))goto cleanup;
    if(strcmp(path,"/api/v1")!=0)goto cleanup;
    if(strcmp(scheme,"https")!=0 && !(strcmp(scheme,"http")==0 && (!strcmp(host,"localhost")||!strcmp(host,"127.0.0.1")) && !strcmp(kdp_env("KDP_ALLOW_LOOPBACK"),"1")))goto cleanup;
    {CURLUPart forbidden[]={CURLUPART_USER,CURLUPART_PASSWORD,CURLUPART_QUERY,CURLUPART_FRAGMENT};
    for(size_t i=0;i<sizeof(forbidden)/sizeof(forbidden[0]);i++){if(curl_url_get(url,forbidden[i],&part,0)==CURLUE_OK)goto cleanup;}}
    target=(char *)malloc(strlen(base)+strlen(route)+1);if(!target)goto cleanup;strcpy(target,base);strcat(target,route);
    if(!kdp_header(&headers,"Accept","application/json")||!kdp_header(&headers,"User-Agent","KDPikaDocsExample/1.0 Native"))goto cleanup;
    if(!strcmp(auth,"publicApp")&&(!kdp_header(&headers,"X-App-ID",kdp_required("KDP_APP_ID"))||!kdp_header(&headers,"X-Environment","SANDBOX")))goto cleanup;
    if(!strcmp(auth,"activation")){
        const char *token=kdp_required("KDP_ACTIVATION_TOKEN");if(!token)goto cleanup;
        char *bearer=(char *)malloc(strlen(token)+8);if(!bearer)goto cleanup;strcpy(bearer,"Bearer ");strcat(bearer,token);
        int ok=kdp_header(&headers,"Authorization",bearer);free(bearer);if(!ok)goto cleanup;
    }
    if(!strcmp(argv[1],"validate")&&!kdp_header(&headers,"X-Installation-ID",kdp_required("KDP_INSTALLATION_ID")))goto cleanup;
    curl=curl_easy_init();if(!curl)goto cleanup;
    curl_easy_setopt(curl,CURLOPT_URL,target);curl_easy_setopt(curl,CURLOPT_CUSTOMREQUEST,method);
    curl_easy_setopt(curl,CURLOPT_FOLLOWLOCATION,0L);curl_easy_setopt(curl,CURLOPT_CONNECTTIMEOUT,5L);curl_easy_setopt(curl,CURLOPT_TIMEOUT,15L);
    curl_easy_setopt(curl,CURLOPT_SSL_VERIFYPEER,1L);curl_easy_setopt(curl,CURLOPT_SSL_VERIFYHOST,2L);
    curl_easy_setopt(curl,CURLOPT_WRITEFUNCTION,kdp_receive);curl_easy_setopt(curl,CURLOPT_WRITEDATA,&buffer);
    if(!strcmp(method,"POST")){
        bodydoc=yyjson_read(body,strlen(body),0);if(!bodydoc||!yyjson_is_obj(yyjson_doc_get_root(bodydoc)))goto cleanup;
        if(!kdp_header(&headers,"Content-Type","application/json"))goto cleanup;
        curl_easy_setopt(curl,CURLOPT_POSTFIELDS,body);
    }
    curl_easy_setopt(curl,CURLOPT_HTTPHEADER,headers);if(curl_easy_perform(curl)!=CURLE_OK)goto cleanup;
    curl_easy_getinfo(curl,CURLINFO_RESPONSE_CODE,&status);
    result=yyjson_read(buffer.data,buffer.size,0);if(!result||!yyjson_is_obj(yyjson_doc_get_root(result)))goto cleanup;
    printf("%s\n",buffer.data);
    code=status>=200&&status<300&&yyjson_is_true(yyjson_obj_get(yyjson_doc_get_root(result),"success"))?0:1;
cleanup:
    if(code)fprintf(stderr,"Request rejected, unavailable or configuration invalid. Inspect JSON error.code/request_id when returned; do not blindly retry mutations.\n");
    if(curl)curl_easy_cleanup(curl);if(url)curl_url_cleanup(url);curl_slist_free_all(headers);
    curl_free(scheme);curl_free(host);curl_free(path);curl_free(part);free(target);free(buffer.data);
    yyjson_doc_free(ops);yyjson_doc_free(bodydoc);yyjson_doc_free(result);return code;
}
```

## 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.

## 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.

## 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 |
| --- | --- | --- |
| RATE_LIMITED (HTTP 429) | Bucket exhausted; wait for window reset; no licensing Retry-After header | After window; apply jitter |
| INVALID_TOKEN (HTTP 401) | Missing/non-act_/unknown/revoked/deactivated activation token | Reactivate eligible installation |
| INVALID_REQUEST (HTTP 422) | Input constraints or entitlement/resource/renewal domain rejection | Correct input/plan; not blind retry |
| DEVICE_NOT_AUTHORIZED (HTTP 403) | Token is active but associated device is not ACTIVE | Reactivation if eligible |
| DEVICE_MISMATCH (HTTP 403) | Provided installation ID does not match token-bound HMAC hash | Use original installation; do not copy token |
| LICENSE_EXPIRED (HTTP 403) | Elapsed expires_at before state check; or EXPIRED state; SDK local expiry has no HTTP | Renew eligible license |
| LICENSE_REVOKED (HTTP 403) | License REVOKED and no elapsed deadline taking precedence | Do not retry; contact developer |
| LICENSE_SUSPENDED (HTTP 403) | License SUSPENDED and no elapsed deadline taking precedence | Restore then reactivate |
| LICENSE_CANCELLED (HTTP 403) | License CANCELLED and no elapsed deadline taking precedence | Do not retry; new eligible license |
| LICENSE_PENDING (HTTP 403) | License PENDING and no elapsed deadline taking precedence | Wait for authorized activation |
| INTERNAL_ERROR (HTTP 500) | Uncaught exception at global boundary | Safe retry only for idempotent operation; preserve request_id |

## 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)