Retrieve a license

Read a scoped unsigned license summary.

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.
• Read API conventions and authentication.
• Keep customer credentials private and management keys on your trusted backend.

Method and path

GET /api/v1/licenses/{license}

When to use it

Read an unsigned management summary from your trusted backend for support or reconciliation. This is not an activation response, a list operation or a replacement for signed installation validation.

Authentication and environment

Use Authorization: Bearer YOUR_DEVELOPER_API_KEY with scope licenses:read. The key fixes the organization/product/environment; X-Environment cannot override it.

Request headers

Path and query parameters

No pagination, filtering, sorting or list query parameters are implemented. Use JSON rather than relying on alternate form/query parsing.

Request body

No request body is consumed. Send this GET request without a body.

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

{
  "success": true,
  "license": {
    "id": "lic_578581bd80c2a672da30fc29",
    "license_key_mask": "TESTDOCS-••••-••••-HAHH",
    "status": "active",
    "environment": "sandbox",
    "starts_at": "2026-10-17T10:39:35+00:00",
    "expires_at": "2026-11-16T10:39:35+00:00",
    "created_at": "2026-10-17T12:39:35+00:00",
    "updated_at": "2026-10-17T12:39:35+00:00",
    "max_devices": 2,
    "active_devices": 0,
    "max_activations": 4,
    "activation_count": 0,
    "min_version": null,
    "max_version": null,
    "revocation_reason": null,
    "product": {
      "id": "app_a642cd24641ec976626b",
      "name": "Docs fixture product"
    },
    "plan": {
      "id": "plan_3bf54c099326639ee183661f",
      "name": "Fixture plan",
      "slug": "fixture-plan",
      "billing_type": "monthly",
      "price": 19.5,
      "currency": "EUR"
    },
    "customer": {
      "id": "cus_d7db5516f8377f89a869e293",
      "name": "Synthetic contract customer",
      "email": "contract-6b9f0843f1d3609f@example.invalid",
      "company": null,
      "country": null
    }
  },
  "request_id": "req_2e71dc11a311d6a5d34c50cb"
}

Response fields

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.

Error responses

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 keeps SDK-local and operational namespaces separate.

Side effects

Reads the scoped license/customer/product/plan summary and active-device count. Does not reveal the complete key, issue a token, mutate license state or emit an audit/webhook/email. Successful key authentication updates the developer key's last-used timestamp. Customer fields are personal data: restrict the response to authorized operators.

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

GET is safe to retry with bounded backoff. No Idempotency-Key is consumed. A summary is a snapshot, not a caller version/ETag concurrency precondition; do not use it as a lock before another mutation.

Rate limits

Developer pre-authentication:240 per60 seconds per IP. Scoped reads:180 per60 seconds per developer-key license-read 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 before granting access.

cURL

Save every file shown below. Install the exact runtime/dependencies from the complete example archive README. Set the endpoint request JSON in KDP_BODY_JSON and the documented KDP_* credential variables in your private process environment.

Run sh request.sh get-license. Expected: full JSON, exit 0 for success, exit 1 for an API rejection; exit 2 for setup/transport failure. The cURL sample checks HTTP status; parse JSON before use. Never authorize a feature from transport output alone.

#!/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

Expected result

A correctly authenticated eligible request returns the documented HTTP status and schema. Check the actual success/error result and request IDs; 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 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

Next steps

Read idempotency and signed responses before integrating a purchase-to-license workflow.

Related

• API conventions
• Errors
• License lifecycle