Getting Started

Authentication

Three authentication methods for different trust levels and use cases.

API Key

Server-side management. Full CRUD on all resources with scoped permissions.

Bearer lk_live_...

License Key

Client-side operations. Machine activation, heartbeats, deactivation.

License PREFIX-...

No Auth

License validation only. Key in request body, no secrets exposed.

POST /validate-key

API Key Authentication

API keys are used for management operations — creating products, issuing licenses, configuring policies, and reading analytics. They grant full access to your account’s resources based on assigned scopes.

Authorization header

# Live environment
Authorization: Bearer lk_live_your_api_key_here

# Test environment
Authorization: Bearer lk_test_your_api_key_here

Example: list licenses

curl -X GET https://your-instance.licentric.com/api/v1/licenses \
  -H "Authorization: Bearer lk_live_abc123def456..."

Key Prefixes

Prefix	Environment	Usage
lk_live_	Production	Real licenses, live data
lk_test_	Test / Sandbox	Development, integration testing

API Key Scopes

Each API key can be assigned specific scopes that restrict which operations it can perform. When creating a key, select only the scopes your integration needs.

Scope	Description	Operations
licenses:read	List and retrieve licenses	GET /licenses, GET /licenses/:id
licenses:write	Create, update, and delete licenses	POST, PATCH, DELETE /licenses
machines:read	List and retrieve machines	GET /machines, GET /machines/:id
machines:write	Create and delete machines	POST, DELETE /machines
products:read	List and retrieve products	GET /products, GET /products/:id
products:write	Create, update, and delete products	POST, PATCH, DELETE /products
policies:read	List and retrieve policies	GET /policies, GET /policies/:id
policies:write	Create, update, and delete policies	POST, PATCH, DELETE /policies
entitlements:read	List and retrieve entitlements	GET /entitlements
entitlements:write	Create and delete entitlements	POST, DELETE /entitlements
webhooks:read	List and retrieve webhook endpoints	GET /webhooks, GET /webhooks/:id
webhooks:write	Create, update, and delete webhooks	POST, PATCH, DELETE /webhooks
analytics:read	Access license and usage analytics	GET /analytics/*

Security best practices

Store API keys in environment variables — never in source code
Use test keys (lk_test_) during development
Assign the minimum scopes required for your use case
Rotate keys immediately if you suspect exposure
API keys are stored as SHA-256 hashes — the raw key is shown only once

License Key Authentication

License key auth is used for operations scoped to a single license — activating machines, sending heartbeats, and deactivating devices. This is the auth method used in end-user applications.

License key header

Authorization: License PROAPP-A1B2-C3D4-E5F6-G7H8

Example: activate a machine

# Activate a machine using license key auth
curl -X POST https://your-instance.licentric.com/api/v1/machines \
  -H "Authorization: License PROAPP-A1B2-C3D4-E5F6-G7H8" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": "ab12cd34ef56",
    "name": "Workstation-1"
  }'

License keys are safe for client-side use

Unlike API keys, license keys only grant access to their own license record. They cannot list other licenses, create products, or access account-wide data. This makes them safe to embed in end-user applications.

Unauthenticated: Validate Key

The POST /licenses/validate-key endpoint requires no authentication. The license key is passed in the request body, and the API returns the validation result.

Validate a license key

# No authentication header required
curl -X POST https://your-instance.licentric.com/api/v1/licenses/validate-key \
  -H "Content-Type: application/json" \
  -d '{
    "key": "PROAPP-A1B2-C3D4-E5F6-G7H8",
    "fingerprint": "ab12cd34ef56",
    "entitlements": ["export_pdf"]
  }'

Validation response

{
  "valid": true,
  "code": "VALID",
  "license": {
    "id": "lic_01H...",
    "status": "active",
    "expiresAt": "2027-01-01T00:00:00Z"
  }
}

Validation Codes

The validation response includes a code field indicating why a license is valid or invalid.

Code	Meaning
VALID	License is valid and the request succeeded
NOT_FOUND	No license exists with the provided key
EXPIRED	License has passed its expiration date
SUSPENDED	License has been temporarily suspended
REVOKED	License has been permanently revoked
BANNED	License has been flagged for abuse
MACHINE_LIMIT_EXCEEDED	Maximum machine activations reached
FINGERPRINT_NOT_FOUND	Device fingerprint not activated for this license
HEARTBEAT_REQUIRED	Machine heartbeat is overdue
USES_EXCEEDED	License has exceeded its maximum validation count
ENTITLEMENTS_MISSING	Required entitlements are not attached to the license

Choosing an Auth Method

Scenario	Auth Method
Your backend creates / manages licenses	API Key
End-user app activates / deactivates devices	License Key
End-user app checks if license is valid	None (validate-key)
Webhook receives events from Licentric	HMAC-SHA256

Next Steps

Follow the Desktop App guide to integrate license key auth in a desktop application.
Set up Webhooks and learn about HMAC signature verification.

Architecture Desktop App