---
order: 5
slug: "/docs/v1/start/core-concepts"
title: "Core concepts"
section: "Start here"
description: "Learn the relationships between your workspace, products, plans, customers, licenses, installations, tokens and events."
audience: "all"
level: "beginner"
last_updated: "2026-10-17"
version: "v1"
related: ["/docs/v1/start/quickstart","/docs/v1/start/glossary"]
draft: false
---
A [product plan](/docs/v1/start/glossary#product-plan) describes access rules; a [license](/docs/v1/start/glossary#license) grants those rules to one [customer](/docs/v1/start/glossary#customer) in one environment.

## What you will learn
- How the main records relate.
- Which identifiers are public and which are secrets.
- Which limits and environments belong to which layer.

## Prerequisites
- Read the [introduction](/docs/v1/start/introduction).
- Use the [glossary](/docs/v1/start/glossary) when comparing similar names.

## Relationships
![An organization owns products and customers. A product has product plans and features. A customer license references one plan and environment; devices and activation tokens belong to that license.](/docs/diagrams/p4-concepts.svg)

An organization owns products and customers. A product has product plans and features. A customer license references one plan and environment; devices and activation tokens belong to that license.

## Record reference
| Concept | Purpose | Important distinction |
| --- | --- | --- |
| [Organization](/docs/v1/start/glossary#organization) | Tenant owning the workspace records and [platform subscription](/docs/v1/start/glossary#platform-subscription) | Not a software buyer account |
| [Product](/docs/v1/start/glossary#product) | Your application definition, [public App ID](/docs/v1/start/glossary#public-app-id) and validation policy | Shared configuration across [Sandbox](/docs/v1/start/glossary#sandbox) and [Live](/docs/v1/start/glossary#live) |
| Public App ID | Nonsecret product identifier supplied as X-App-ID during [activation](/docs/v1/start/glossary#activation) | Not a secret [developer API key](/docs/v1/start/glossary#developer-api-key) |
| Product plan | Template for duration, [features](/docs/v1/start/glossary#feature), [device](/docs/v1/start/glossary#device) and cumulative activation limits | Its price is metadata, not a buyer checkout |
| Feature or entitlement | A named boolean or typed JSON value returned in signed data | Your app must enforce it after validation |
| Customer | Your software buyer or license recipient | Distinct from you paying KDPika |
| License | Customer/product/plan/environment access record with status and optional expiry | Not the printable [license key](/docs/v1/start/glossary#license-key) alone |
| License key | Secret used to activate a license | Copy it at issuance; listings show a mask |
| [Installation ID](/docs/v1/start/glossary#installation-id) | Stable random identity generated and persisted by your app | Not a MAC address or serial number |
| Device | Server record for a hashed installation identity | Not guaranteed unique physical hardware |
| Activation | Registering an installation and obtaining a token | Active seats and cumulative activations differ |
| [Activation token](/docs/v1/start/glossary#activation-token) | Secret used to validate or deactivate the activated installation | Bound to its license/device; do not share |
| Environment | Sandbox or Live boundary for licenses, customers, credentials and endpoints | Not the payment provider's Test/Live mode |
| Developer API key | Scoped server-side credential for management | Never distribute in application binaries |
| [Webhook](/docs/v1/start/glossary#webhook) | Signed outbound notification to your backend | Not an authority that decides license validity |

## Product and platform plans
Your platform subscription defines workspace capacity and billing. Your own product plans define what your customers may use. A monthly product plan does not automatically charge a buyer or renew a license after a sale.
Products, plans and features are shared configuration. Licenses and customers belong to an environment; devices inherit that environment through the license. Usage totals can span both licensing environments.

## Features and changes
Require a valid result before reading a feature. Current helpers can expose a payload value even when the result is invalid; the caller must apply the validity guard.
Device and cumulative activation limits are copied when issuing a license. Changing the product plan does not retroactively replace those copies. Feature resolution uses plan features with license-level overrides; an offline app cannot see a fresh change before reconnecting.

## Expected result
You can trace a customer license to its product, plan, environment, devices and token without confusing it with a platform billing subscription.

## Common mistakes
- Counting active licenses as activation requests: a license can have multiple devices and many validations.
- Resetting devices to clear cumulative activations: reset releases seats and revokes tokens, not that counter.
- Treating a feature as a usage meter: implement metering and business rules in your own backend.

## Security notes
Customer emails and metadata can be personal data. Hashing an installation ID does not automatically make the complete record anonymous. Avoid unnecessary personal data in labels and metadata.

## Troubleshooting
| Symptom | Cause | Fix |
| --- | --- | --- |
| Existing limit did not change after editing a plan | The license stores its issued limits | Review the individual license and supported management operations |
| More than one device uses one license | Its per-license device policy allows it | Review max_devices and your transfer policy |
| A plan's price appears in a response but no charge occurs | Licensing metadata is not payment processing | Use your own confirmed payment/fulfilment flow |

## Next steps
Read [authentication](/docs/v1/start/authentication) and the [license lifecycle](/docs/v1/start/license-lifecycle).

## Related
- [Glossary](/docs/v1/start/glossary)
- [Environments](/docs/v1/start/environments)
- [Activation flow](/docs/v1/start/activation-validation-deactivation)