LicenseVault — Secure Software License Management

Documentation

Everything you need to
get started fast

Complete reference for LicenseVault — from quick start to advanced API usage, SDK integration, and security best practices.

⚡ Quick Start

Get LicenseVault up and running in under 10 minutes. Follow these steps to issue your first license and validate it via the API.

Step-by-step Setup

Create a Product

Go to Products → New Product. Enter a name, set the key format (e.g. LV-XXXX-XXXX-XXXX-XXXX), maximum activations per license, and expiry rules.

Add a Customer

Go to Customers → New Customer. Add the customer's name and email. Customers are linked to licenses for tracking and support.

Generate a License Key

Go to Generate, select your product and customer, set the expiry date, and click Generate. A signed license key is created instantly.

Get Your API Key

Go to Products → your product → API Keys. Copy the product API key — this is required to authenticate all license API calls for this product.

Call the Activate Endpoint

From your software, call POST /api/v1/license/activate with the license key, device fingerprint, and your product API key.

# Activate a license key curl -X POST https://your-domain.com/api/v1/license/activate \ -H "X-API-Key: pk_your_product_api_key" \ -H "Content-Type: application/json" \ -d '{ "license_key": "LV-XXXX-XXXX-XXXX", "fingerprint": "sha256:a3f9b1c2d4e5...", "hostname": "workstation-01" }' # Response { "status": "success", "valid": true, "token": "eyJ0eXAiOiJKV1QiLCJhbGci...", "expires_at": "2027-01-01T00:00:00Z" }

💡 The returned JWT token should be stored locally in your application and sent as Authorization: Bearer <token> on subsequent validate calls to avoid extra server round-trips.

✅ Requirements

LicenseVault is a self-hosted PHP application. Make sure your server meets the following requirements before installation.

Server Requirements

The following software must be installed and available on your server:

PHP 8.1+ MySQL 5.7+ / 8.0 Nginx / Apache Composer 2.x

PHP Extensions

The following PHP extensions must be enabled:

openssl pdo_mysql mbstring json curl gd intl

Installation Steps

# 1. Clone / upload the application files to your server git clone https://github.com/your-org/licensevault.git cd licensevault # 2. Install PHP dependencies composer install --no-dev --optimize-autoloader # 3. Copy environment file and configure cp .env.example .env # Edit .env: set database credentials, base URL, app key # 4. Run database migrations php spark migrate # 5. Seed default admin account php spark db:seed LicenseVaultSeeder # 6. Set folder permissions chmod -R 775 writable/

⚠️ Point your web server's document root to the public/ directory. Never expose the application root directly.

📊 Dashboard Overview

The LicenseVault dashboard gives you a real-time overview of your entire licensing operation from a single screen.

Dashboard Metrics

The main dashboard displays key metrics at a glance:

Metric	Description
Total Licenses	Total number of license keys issued across all products.
Active Licenses	Licenses that are currently active and have been activated at least once.
Total Activations	Cumulative count of all device activations across all licenses.
Total Products	Number of software products registered in the system.
Total Customers	Number of customer records linked to at least one license.
Recent Activity	Live feed of the latest API calls, activations, and system events.

Navigation Structure

The left sidebar provides access to all major sections:

DashboardOverview metrics and recent activity log

ProductsManage software products and API keys

LicensesIssue, search, filter and manage license keys

CustomersCustomer directory linked to licenses

ActivationsDetailed log of every device activation

GenerateManually create new license keys

DownloadsSoftware release management

EnvatoEnvato purchase code redemption logs

SettingsSMTP, security, Envato API configuration

📦 Products

Products represent your software applications. Each product has its own key format, activation rules, and API key for license operations.

Creating a Product

Navigate to Products → New Product and fill in the following fields:

Field	Description
Name	Display name for your software product (e.g. "DataSync Pro").
Slug	URL-safe identifier. Auto-generated from name. Used in API calls.
Key Format	Pattern for generated keys. Use `X` for random chars (e.g. `LV-XXXX-XXXX-XXXX`).
Max Activations	Maximum number of devices a single license can be activated on.
Expiry Days	Default license duration in days. Leave blank for lifetime licenses.
Features	JSON object of feature flags/entitlements for all licenses of this product.

Product API Keys

Each product has one or more API keys used to authenticate license API requests. Keys are scoped to a single product — they cannot be used to access other products' licenses.

ℹ️ API keys are prefixed with pk_. Rotate keys immediately if compromised. Old keys are instantly invalidated upon rotation.

🔑 Licenses

Licenses are cryptographically signed keys that authorize a customer to use your software. Each license is tied to a product and optionally a customer.

License Statuses

Status	Description
active	License is valid and can be activated/validated. Default status after generation.
suspended	Temporarily disabled. Validation fails. Can be re-activated by an admin.
revoked	Permanently disabled. Cannot be re-activated. Validation always fails.
expired	Expiry date has passed. Validation returns an expired error.
trial	Time-limited trial license with restricted features or activations.

License Fields

Field	Description
license_key	The unique signed key string delivered to the customer.
product_id	The product this license belongs to.
customer_id	Optional — the customer this license is assigned to.
max_activations	Maximum concurrent device activations allowed.
expires_at	Optional expiry date. Null means lifetime license.
features	JSON overrides for product-level feature flags.
notes	Internal admin notes. Not visible to customers.

💡 Use bulk generate from the Generate page to issue hundreds of licenses at once for distribution campaigns or reseller batches.

👥 Customers

Customers represent the end-users or organizations that own licenses. Linking licenses to customers enables support lookups, usage tracking, and renewal management.

Customer Fields

Field	Description
Name	Full name or company name of the customer.
Email	Primary contact email. Used for license delivery and renewal notifications.
Company	Optional company/organization name.
Notes	Internal notes visible only to admins.
Licenses	All licenses linked to this customer, visible from the customer detail page.

Customer Actions

From the customer detail page you can:

→

View all licenses

See every license assigned to this customer, including status and activation count.

→

Generate a new license

Issue a new license key directly from the customer profile with one click.

→

View activation history

See all devices that have activated licenses belonging to this customer.

📡 Activations

Every time a license is activated on a device, an activation record is created. These records contain device fingerprint, hostname, IP, and timestamps.

Activation Record Fields

Field	Description
fingerprint	SHA-256 device fingerprint provided by the client application.
hostname	Machine hostname reported at activation time.
ip_address	IP address of the activating machine.
activated_at	Timestamp of the activation event.
last_seen_at	Timestamp of the most recent validation from this device.
is_active	Whether this activation slot is currently in use.

Managing Activations

Admins can deactivate individual activation slots from the Activations page. This frees up a slot so the customer can activate on a new device. Useful when a customer replaces a machine.

⚠️ Once max activations are reached, new activation attempts return a max_activations_reached error. Deactivate an existing slot to free space.

⬇️ Downloads & Releases

Manage versioned software releases and control download access. Only customers with an active license can download protected releases.

Creating a Release

Go to Downloads → New Release and fill in:

Field	Description
Product	Which product this release belongs to.
Version	Semantic version string (e.g. `2.4.1`).
Release Notes	Changelog or description of what's new in this version.
File / URL	Upload the binary or point to an external download URL.
Visibility	Public (anyone can see) or Private (requires active license).
Minimum License Type	Only licenses of this type or higher can download the release.

ℹ️ The Auto Update API endpoint (/api/v1/license/latest-release) allows your app to check for updates automatically using the customer's license key.

⚡ API Overview

LicenseVault provides a RESTful JSON API for all license operations. All endpoints require an X-API-Key header with your product API key.

Base URL & Authentication

# Base URL https://your-domain.com/api/v1 # Authentication header (required on all requests) X-API-Key: pk_your_product_api_key # Content type Content-Type: application/json

Available Endpoints

Method	Endpoint	Description
POST	/license/activate	Activate a license on a device
POST	/license/validate	Validate a license or JWT token
POST	/license/deactivate	Remove a device activation slot
POST	/license/offline-token	Generate a signed offline token
GET	/license/public-key	Retrieve the RSA public key

Error Response Format

{ "status": "error", "error": "license_not_found", // machine-readable code "message": "The provided license key was not found." }

Common error codes:

license_not_found license_expired license_suspended license_revoked max_activations_reached invalid_api_key activation_not_found

🔓 Activate License

Activates a license key on a specific device. On success, returns a signed JWT token for subsequent validate calls.

POST /api/v1/license/activate

Request body parameters:

Parameter	Type	Required	Description
license_key	string	Required	The license key to activate (e.g. LV-XXXX-XXXX-XXXX).
fingerprint	string	Required	Unique device identifier (SHA-256 hash recommended).
hostname	string	Optional	Machine hostname for activation records.
metadata	object	Optional	Additional JSON metadata stored with the activation.

// Request POST /api/v1/license/activate X-API-Key: pk_your_product_api_key { "license_key": "LV-XXXX-XXXX-XXXX", "fingerprint": "sha256:a3f9b1c2d4e5f67890abcdef", "hostname": "dev-workstation-01" } // Success Response (200) { "status": "success", "valid": true, "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...", "license": { "key": "LV-XXXX-XXXX-XXXX", "product": "DataSync Pro", "expires_at": "2027-01-01T00:00:00Z", "features": { "analytics": true, "export": true } } }

✅ Validate License

Validates an active license or JWT token. Call this on every application startup to ensure the license is still valid.

POST /api/v1/license/validate

Parameter	Type	Required	Description
license_key	string	Required*	License key to validate. Required if token not provided.
token	string	Required*	JWT token from a previous activation. Required if license_key not provided.
fingerprint	string	Optional	Device fingerprint to verify the token was issued for this machine.

// Validate by license key { "license_key": "LV-XXXX-XXXX-XXXX", "fingerprint": "sha256:a3f9b1c2..." } // Validate by JWT token (faster, no DB lookup) { "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..." } // Response { "status": "success", "valid": true, "expires_at": "2027-01-01T00:00:00Z", "features": { "analytics": true } }

💡 For best performance, validate using the JWT token field. This uses RSA signature verification locally and avoids a database query — response time is typically under 5ms.

🚫 Deactivate License

Removes the activation for a specific device fingerprint. Use this when a user uninstalls your software to free up their activation slot.

POST /api/v1/license/deactivate

Parameter	Type	Required	Description
license_key	string	Required	The license key to deactivate a device from.
fingerprint	string	Required	The device fingerprint of the activation to remove.

// Request { "license_key": "LV-XXXX-XXXX-XXXX", "fingerprint": "sha256:a3f9b1c2d4e5f67890abcdef" } // Response (200) { "status": "success", "message": "License deactivated successfully." }

📡 Offline Token

Generate a signed offline token for air-gapped or intermittently connected environments. The token is cryptographically signed and can be verified locally without a server call.

POST /api/v1/license/offline-token

Parameter	Type	Required	Description
license_key	string	Required	Active license key to generate token for.
fingerprint	string	Required	Device fingerprint that the token is bound to.
valid_days	integer	Optional	How many days the offline token remains valid (default: 30).

// Request { "license_key": "LV-XXXX-XXXX-XXXX", "fingerprint": "sha256:a3f9b1c2...", "valid_days": 90 } // Response — save this token to a local .lic file { "status": "success", "offline_token": "LVOFF.eyJrZXkiOiJMVi00...", "expires_at": "2026-08-16T00:00:00Z" }

Verifying Offline Tokens Locally (PHP)

use LicenseVault\SDK\OfflineVerifier; // Load the public key once at startup $verifier = new OfflineVerifier('/path/to/public.pem'); $result = $verifier->verify( $offlineToken, $deviceFingerprint ); if ($result->valid) { // Grant access }

⚠️ Offline tokens are bound to the device fingerprint provided at generation. They will fail verification if used on a different machine.

📚 PHP SDK

The official LicenseVault PHP SDK simplifies integration into any PHP application. Download it from the dashboard under Developer Tools → SDK.

Installation

# Via Composer (recommended) composer require licensevault/php-sdk # Or manually — copy LicenseVaultSDK.php into your project require_once 'LicenseVaultSDK.php';

Basic Usage

use LicenseVault\SDK\LicenseVaultSDK; $sdk = new LicenseVaultSDK([ 'api_key' => 'pk_your_product_api_key', 'server_url' => 'https://your-domain.com', ]); // Activate $result = $sdk->activate( 'LV-XXXX-XXXX-XXXX', $sdk->getFingerprint() ); // Validate on startup $valid = $sdk->validate( $storedToken, $sdk->getFingerprint() ); if (!$valid->valid) { exit('License invalid or expired.'); } // Deactivate on uninstall $sdk->deactivate('LV-XXXX-XXXX-XXXX', $sdk->getFingerprint());

SDK Methods Reference

Method	Description
activate($key, $fp)	Activate a license. Returns token + license data.
validate($token, $fp)	Validate a JWT token. Returns validity + expiry.
deactivate($key, $fp)	Remove activation for this device.
getOfflineToken($key, $fp)	Request a signed offline token.
getFingerprint()	Auto-generate a device fingerprint from system info.
getPublicKey()	Fetch the RSA public key for local verification.
checkForUpdates($key)	Check for newer software releases.

🛒 Envato Integration

LicenseVault has built-in support for Envato marketplace. Customers can redeem their ThemeForest or CodeCanyon purchase codes for a LicenseVault license automatically.

Setup

Get your Envato API Token

Log in to your Envato account, go to Account → My Apps → Create Token. Enable "View and search Envato sites" and "View the user's items' purchase data" scopes.

Configure LicenseVault

Go to Settings → Envato. Enter your Envato API token and your Item ID (the numeric ID from your marketplace listing URL).

Link to a Product

In the Envato settings, select which LicenseVault product purchase code redemptions should generate licenses for.

Share the Redemption URL

Provide customers with your redemption page URL. They enter their purchase code and receive a LicenseVault key instantly.

Redemption API Endpoint

POST /api/v1/envato/redeem { "purchase_code": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "email": "customer@example.com" } // Success Response { "status": "success", "license_key": "LV-8YZ2-R0CF-A4JS", "message": "License created and sent to your email." }

⚠️ Each Envato purchase code can only be redeemed once. Subsequent attempts return a purchase_code_already_used error to prevent license cloning.

⚙️ Settings

Configure LicenseVault's core behaviour from the Settings panel. Changes take effect immediately without requiring a restart.

General Settings

Setting	Description
App Name	Name displayed in emails and the UI.
Base URL	Your application's public URL.
Timezone	Used for expiry dates and logs.
Default Expiry Days	Fallback expiry for new licenses without a set expiry.

Email / SMTP

Setting	Description
SMTP Host	Your SMTP server hostname.
SMTP Port	Usually 587 (TLS) or 465 (SSL).
SMTP Username	SMTP authentication username.
SMTP Password	SMTP authentication password.
From Email	Sender address for all outbound emails.

Security Settings

Setting	Description
Rate Limit (per minute)	Max API requests per IP per minute. Requests over the limit return HTTP 429.
JWT Expiry Hours	How long issued JWT tokens remain valid before requiring re-validation.
RSA Key Pair	Generate or rotate the RSA-2048 key pair used for license signing. Keep the private key secret.
IP Whitelist	Optional — restrict Admin API access to specific IP addresses.

🔒 Security

LicenseVault uses multiple layers of security to protect your licenses from tampering, cloning, and replay attacks.

🔐 RSA-2048 Signing

Every license token is signed using your private RSA-2048 key. Clients verify authenticity using only the public key — the private key never leaves your server.

🖥️ Device Binding

Licenses are bound to device fingerprints at activation time. Tokens issued for one machine will fail verification on another, preventing license sharing.

⚡ Rate Limiting

All API endpoints are protected by per-IP rate limiting. Brute-force attempts against license keys are throttled automatically with HTTP 429 responses.

🛡️ API Key Scoping

Product API keys are scoped to a single product. A compromised key for one product cannot be used to access or modify licenses for other products.

Security Best Practices

✓

Store API keys server-side

Never embed product API keys in client-side or distributed application code. Keep them in server-side configuration only.

✓

Use HTTPS exclusively

Always serve LicenseVault over HTTPS. TLS prevents man-in-the-middle attacks on license key transmission.

✓

Rotate RSA keys periodically

Regenerate your RSA key pair every 12–24 months. After rotation, re-issue tokens to active customers — old tokens will be invalidated.

✓

Validate on every startup

Call the validate endpoint on every application launch, not just once. This ensures suspended or revoked licenses are blocked promptly.

✓

Use strong device fingerprints

Combine multiple hardware identifiers (CPU ID, MAC address, disk serial) before hashing. Single-attribute fingerprints are easier to spoof.

License Management
Built for the Future

Everything you need to
protect your software

Up and running
in minutes

Simple, transparent
pricing

Loved by
developers

Everything you need to
get started fast

License Management Built for the Future

Everything you need toprotect your software

Up and runningin minutes

Simple, transparentpricing

Loved bydevelopers

Everything you need toget started fast

License Management
Built for the Future

Everything you need to
protect your software

Up and running
in minutes

Simple, transparent
pricing

Loved by
developers

Everything you need to
get started fast