How To: Configure Licensing¶

This guide covers all the licensing options available in PyLocket: device limits, expiration dates, offline grace periods, and license types.

Device Limits¶

Each license allows activation on a limited number of devices. Set the limit when creating a license:

pylocket licenses create \
  --app <APP_ID> \
  --email customer@example.com \
  --device-limit 3

Device Limit	Use Case
1	Single-seat personal license
2	Home + work (most common default)
3	Small team or multi-device user
5+	Team or site license

Resetting Device Activations¶

When a customer replaces a device or reinstalls their OS, their activation slot is consumed. Reset their activations to let them re-activate:

pylocket licenses reset-devices --license <LICENSE_KEY>

This clears all device records for the license without changing its status.

License Expiration¶

Create time-limited licenses by setting an expiration date:

pylocket licenses create \
  --app <APP_ID> \
  --email customer@example.com \
  --device-limit 2 \
  --expires 2027-01-01

When a license expires: - The status changes to EXPIRED - The next token refresh attempt fails - The application displays an expiration message

Subscription-Style Licenses¶

For subscription-based products, create licenses with short expiration windows and extend them on renewal:

# Create a 1-month license
pylocket licenses create \
  --app <APP_ID> \
  --email customer@example.com \
  --device-limit 2 \
  --expires 2026-04-01

# Extend on renewal
pylocket licenses extend \
  --license <LICENSE_KEY> \
  --expires 2026-05-01

Offline Grace Period¶

After online activation, the application works offline for a configurable grace period.

The offline grace period is configured at the app level:

pylocket apps update \
  --app <APP_ID> \
  --offline-grace-hours 168  # 7 days

Grace Period	Use Case
Short	High-security applications
Standard (default)	Balanced security and usability
Extended	Users in intermittent-connectivity environments
Long	Largely offline deployments

Note: Longer grace periods reduce security because stolen tokens remain valid longer. Balance usability with your security requirements.

License Types¶

Standard License (`ACTIVE`)¶

The default license type. Full access to the protected application.

Demo License (`DEMO`)¶

A limited license for trials or demos:

pylocket licenses create \
  --app <APP_ID> \
  --email prospect@example.com \
  --type demo \
  --expires 2026-04-01

Your application can check the license type at runtime and enable/disable features accordingly. The license type is included in the runtime token payload.

Tip: For a quick trial distribution workflow without manual license creation, use Direct Distribution. Free-tier direct downloads automatically create licenses that expire after 60 days — ideal for evaluation.

Velocity Controls¶

PyLocket includes built-in anti-abuse mechanisms:

Control	Default	Description
Activation velocity	Rate-limited	Max activations per license in a rolling time window
Download velocity	Rate-limited	Limits rapid download requests

These prevent automated license key sharing and brute-force activation attempts. They are enabled by default and cannot be disabled.

Silent Activation with Environment Variables¶

For server deployments, Docker containers, or CI/CD environments where interactive prompts are not practical, set the PYLOCKET_LICENSE_KEY environment variable. The protected application will use it to activate automatically without prompting the user:

export PYLOCKET_LICENSE_KEY="XXXX-XXXX-XXXX-XXXX"
./myapp

This is also useful for automated testing of your protected application.

Monitoring License Usage¶

Developer Portal¶

The Licenses dashboard shows:

Total licenses by status (active, revoked, expired)
Activation count per license
Device activations and timestamps
Geographic distribution (based on activation IP)

CLI¶

# List all licenses for an app
pylocket licenses list --app <APP_ID>

# Filter by status
pylocket licenses list --app <APP_ID> --status active

# Get details for a specific license
pylocket licenses get --license <LICENSE_KEY>

REST API¶

# List licenses
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.pylocket.com/v1/licenses?app_id=<APP_ID>

# Get license details
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.pylocket.com/v1/licenses/<LICENSE_ID>

Revoking Licenses¶

Revoke a license immediately:

pylocket licenses revoke --license <LICENSE_KEY>

Revocation takes effect: - Immediately for new activation attempts - At next token refresh for already-activated devices - At offline grace expiry for offline devices