Getting Started

Architecture

How your application communicates with Licentric and how the platform is structured.

Client-Server Model

Licentric operates as a centralized licensing server. Your application acts as the client, making API calls to validate licenses, manage machines, and query license state.

Your Application (client)
        │
        │  HTTPS request
        │  Authorization: Bearer lk_live_... (or License PREFIX-...)
        ▼
   Licentric API
   https://your-instance.licentric.com/api/v1
        │
        ├── Validates auth credentials
        ├── Enforces rate limits
        ├── Processes request
        └── Returns JSON response

Base URL

All API requests are sent to your instance’s base URL:

Base URL

https://your-instance.licentric.com/api/v1

All endpoints are versioned under /api/v1. Future versions will use /api/v2, and existing versions will remain supported.

Authentication Boundaries

The API uses three distinct authentication methods, each suited to a different trust level and use case.

Auth Type	Where Used	Trust Level	Scope
API Key	Your backend server	High — full management access	Create, read, update, delete all resources
License Key	End-user application	Medium — license-scoped	Activate, deactivate, heartbeat for own license
None	Any client	Low — read-only validation	Validate a license key (no secrets exposed)

API keys belong on the server

API keys grant full management access. They must only be used in server-side code — never in client-side applications, desktop apps, or mobile apps where the key could be extracted.

Multi-Tenant Isolation

Licentric is multi-tenant by design. Every record in the database belongs to an account_id, and isolation is enforced at the database level using PostgreSQL Row Level Security (RLS).

Each API key is scoped to a single account
RLS policies ensure queries can never return data from other accounts
Even if application-level auth is bypassed, the database enforces isolation
Admin operations are isolated from tenant data access paths

Offline Mode

For environments without reliable network access (air-gapped deployments, field installations), Licentric supports offline license validation using cryptographically signed license files.

Offline licensing flow

# 1. Generate an offline license file (server-side, API key auth)
curl -X POST /api/v1/licenses/{id}/offline-file \
  -H "Authorization: Bearer lk_live_..." \
  -o license.lic

# 2. The .lic file contains an Ed25519-signed payload with:
#    - License metadata (expiry, entitlements, machine limit)
#    - Policy constraints (offline max days)
#    - Cryptographic signature for tamper detection

# 3. Your application validates offline using the public key
#    No network request required — verification is local

License files are signed with Ed25519 for fast, compact verification
Your application bundles the public key and validates locally — no network call needed
Offline licenses expire after the configured offlineMaxDays and require a check-in to renew
Tampered files are detected and rejected by signature verification

Ed25519 signatures

Licentric uses Ed25519 (EdDSA) for offline license signing. Ed25519 produces 64-byte signatures, is resistant to timing attacks, and verification requires only the 32-byte public key.

Data Flow Summary

Operation	Auth	Direction
Create product, policy, license	API Key	Your server → Licentric API
Validate license at runtime	None	End-user app → Licentric API
Activate / deactivate machine	License Key	End-user app → Licentric API
Receive event notifications	HMAC-SHA256	Licentric API → Your webhook endpoint
Validate offline license	Ed25519 sig	Local (no network)

Next Steps

Learn about Authentication in detail, including API key scopes and best practices.
Explore Offline Licensing for a complete integration guide.

Core Concepts Authentication