Create a license

Issue a license after your backend verifies the buyer purchase.

What you will learn

• Send this exact operation with its required credentials and fields.
• Interpret success, refusal, side effects and retry risks.

Prerequisites

• Complete the Sandbox quickstart.
• Read API conventions and authentication.
• Keep customer credentials private and management keys on your trusted backend.

Method and path

POST /api/v1/licenses

When to use it

Issue a buyer license from your trusted backend after your own store verifies the purchase. KDPika does not collect payment from your software buyers or verify their store receipt on this endpoint.

Authentication and environment

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

Request headers

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

Full request JSON

{
  "product_id": "YOUR_INTERNAL_PRODUCT_ID",
  "plan_id": "YOUR_PRODUCT_PLAN_ID",
  "customer": {
    "email": "customer@example.invalid",
    "name": "Example customer",
    "company": "Example company",
    "external_id": "YOUR_CUSTOMER_REFERENCE"
  }
}

The schemas describe supported recommended input types. Current PHP parsing trims/casts strings and may ignore unknown fields; it is not strict JSON-schema validation. Invalid optional descriptive fields can become empty/null. Conventions describes malformed JSON and alternate parsing.

Success response

HTTP 201. The following is a real isolated Sandbox capture; secret values are replaced with explicit placeholders.

{
  "success": true,
  "license": {
    "id": "lic_578581bd80c2a672da30fc29",
    "license_key": "YOUR_NEW_LICENSE_KEY",
    "expires_at": "2026-11-16T10:39:35+00:00",
    "environment": "sandbox"
  },
  "request_id": "req_1c0f804fd7c455f25fa1f791"
}

Response fields

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

Creates one ACTIVE license and, if needed, one customer scoped by organization/environment/email. An existing customer's descriptive fields are not updated by this call. Duration/trial policy comes from the product plan. Creates audit license.created and queues webhook license.created for matching configured endpoints; no email is sent directly. A stored replay does not issue another license or repeat those creation events. Active-license capacity is checked before creation. The new plaintext key is included in the retained idempotency response for 24 hours; do not call this no-plaintext storage.

Authenticated requests can consume the organization monthly API usage counter once tenant context is established, including some failures. This usage counter is currently warning-only, not a monthly API rejection gate. Developer-key authentication can update last_used_at before a later failure. No request body or Authorization value is saved by the API metadata logger.

Idempotency and concurrency

An 8–190 character Idempotency-Key is mandatory and scoped to the organization, not a single product. The retention window is24 hours. The hash covers PHP JSON encoding of the decoded body; changed member order can conflict. A stored replay returns 201, the original body/request_id/key and Idempotent-Replay:true, with a new current X-Request-ID header. Known expiry/concurrency defects can commit duplicate licenses before 500. Serialize fulfillment by business event on your backend, preserve your durable mapping and reconcile uncertain outcomes instead of blindly choosing a new key. This is not an exactly-once guarantee.

Rate limits

Developer pre-authentication:240 requests per60 seconds per IP. After successful authentication/scope checks:60 per60 seconds per developer-key license-create bucket.

Fixed windows begin with the first hit after expiry. Attempted calls consume every bucket they reach, even if later business validation fails.

Runnable examples

These are complete native HTTP transport programs, not full SDK clients or entitlement verifiers. JSON request bodies and credentials come from KDP_* environment variables. They print raw responses to a private terminal; do not send their stdout to application/CI logs. Use the P5 verification guides before granting access.

JavaScript (Node)

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 node request.mjs create-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.

// 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;
});

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