Getting Started

Core Concepts

The building blocks of software licensing in Licentric.

Entity Overview

Licentric models software licensing through a hierarchy of entities. Each entity maps to an API resource, and understanding their relationships is key to building effective licensing integrations.

  Product
     │
     ├── has many ──▶  License Rules (policies)
     │                        │
     │                        └── used by ──▶  Licenses
     │                                            │
     │                                            ├── activated on ──▶  Devices (machines)
     │                                            │
     │                                            ├── has ──▶  Features (entitlements)
     │                                            │
     │                                            └── belongs to ──▶  Customer
     │
     └── notified via ──▶  Webhooks

Products

A product represents a software title you distribute and want to protect with licensing. Every license is tied to exactly one product.

Each product has a unique code used as the license key prefix
Products can have multiple license rules, each defining different terms
Example: “Pro Desktop App” with code PROAPP

License Rules (Policies)

A license rule defines the constraints and behavior of licenses issued under it. In the API, this entity is called a policy.

Max devices — how many machines can activate the license
Duration — how long the license remains valid (or perpetual)
Offline access — whether the license works without network connectivity
Fingerprinting — whether device fingerprints are required for activation
Heartbeat — whether devices must send periodic check-ins
Floating — whether activations can be released and reused

Templates simplify setup

Use built-in templates (desktop_app, cli_tool, saas, trial) when creating policies to start with sensible defaults for common use cases.

Licenses

A license is a key issued to a customer, tied to a product and governed by a license rule. The license key follows the format PREFIX-XXXX-XXXX-XXXX-XXXX.

License Statuses

Status	Description	Transitions
active	License is valid and usable	Can be suspended or revoked
suspended	Temporarily disabled by the vendor	Can be reinstated or revoked
expired	Past the expiration date	Can be reinstated
revoked	Permanently disabled	Terminal — no further transitions
banned	Flagged for abuse	Terminal — no further transitions

Devices (Machines)

A device represents a physical or virtual machine where a license is activated. In the API, this entity is called a machine.

Identified by a fingerprint — a unique string your application generates from hardware or environment attributes
Activation creates a machine record linked to the license
The policy’s maxMachines limit controls how many devices can be active simultaneously
Floating licenses allow deactivating a device to free up a slot for another

Features (Entitlements)

Features are flags or capabilities attached to individual licenses. In the API, this entity is called an entitlement.

Use entitlements to gate premium features within a single product
Validation can check for required entitlements and return ENTITLEMENTS_MISSING if absent
Example: export_pdf, advanced_analytics, priority_support

Customers

Customers are the people or organizations that hold licenses. Customer records are created automatically when a license is issued with an email address.

A customer can hold multiple licenses across different products
Customers can access the self-service portal to view their licenses and manage devices

Webhooks deliver real-time event notifications to your servers. When a licensing event occurs (license created, machine activated, license expired), Licentric sends an HMAC-signed HTTP POST to your configured endpoint.

Signed with HMAC-SHA256 for payload integrity verification
Retried with exponential backoff on delivery failure
Events are delivered at least once — handlers should be idempotent

Next Steps

Understand the Architecture and how your application communicates with Licentric.
Learn about Authentication methods for API keys and license keys.

Quickstart Architecture