Session-Based Licensing Endpoints

This page describes the licensing/activate, licensing/extend, and licensing/deactivate endpoints and when to use them instead of the basic licensing/validate endpoint.

When to Use Session-Based Licensing

The classic licensing/validate endpoint is stateless: every call independently validates the license token and optional authContext. Misuse detection (too many different authContext values) is handled in the background and may lock a license, but validate itself does not enforce “one active session at a time”.

Session-based licensing is designed for vendors who:

• Want to prevent the same license key from being used in parallel on multiple machines or sessions.
• Still want to allow the end user to use the key on more than one machine, as long as those usages happen at separate time frames (e.g., work PC during the day, laptop at night).

With session-based licensing:

• A license can have at most one active session at any time.
• A session is considered active for 10 minutes from the last successful activity.
• The client must call extend periodically (typically every 10 minutes or less) to keep the session alive.
• A client should call deactivate when the user signs out or closes the application to immediately free the license for another machine.

You can still use licensing/validate for simple checks (e.g., in dashboards or admin tools). Use the session endpoints in your end-user applications where you care about concurrent usage.

Common Request Shape

All three endpoints share the same request body shape as licensing/validate:

{
  "licenseToken": "string",
  "productCodes": ["string"],
  "authContext": "string"
}

Fields

• licenseToken (required): The license key/token.
• productCodes (required): One or more product codes you expect this license to be valid for.
• authContext (recommended): A stable identifier for the current device or environment (machine ID, MAC address, hardware fingerprint, etc.). This is what distinguishes one session from another.

All endpoints return the same ValidationResponse payload described in the Licensing API Integration Guide (including authStatus, contact details, and trial flags).

POST /licensing/activate

Purpose: Start a new session for a given licenseToken and authContext.

Behavior

• Validates the license (same rules as validate).
• If validation succeeds and there is no other active session for this license under a different authContext, the call:
  • Returns authStatus = Success.
  • Starts a new session associated with this authContext.
• If there is another active session for the same license on a different authContext, the call:
  • Returns authStatus = Failed.
  • You should treat this as “license is already in use on another machine/session”.

Session window:
After a successful activate, the session is active for 10 minutes by default. If you do nothing else, the session will expire after that window and another machine will be able to start a new session.

Example client flow

1. User enters license key and logs in.
2. Client calls POST /licensing/activate with:
   • licenseToken: user’s key
   • productCodes: the product they’re trying to use
   • authContext: device/machine identifier
3. If authStatus = Success, allow the user into the app and start a timer to call extend periodically.

POST /licensing/extend

Purpose: Keep an existing session alive for the same licenseToken and authContext.

Behavior

• Uses the same request body as activate.
• Validates the license again.
• If the current session is still valid and belongs to the same authContext, the call:
  • Returns authStatus = Success.
  • Extends the session another 10 minutes from “now”.
• If something changed (license locked, expired, or active session moved to a different authContext), you’ll get authStatus != Success and should react accordingly (e.g., sign the user out, show an error).

Example usage pattern

• After a successful activate, schedule a background task or timer:
  • Every 5–9 minutes (less than the 10-minute window), call POST /licensing/extend with the same licenseToken, productCodes, and authContext.
  • If extend ever returns authStatus != Success, stop the session locally and prompt the user to re-activate or contact support.

This ensures that if the app crashes or the machine goes offline, the session naturally expires within 10 minutes, allowing another machine to activate later.

POST /licensing/deactivate

Purpose: Explicitly end the current session for a given licenseToken and authContext.

Behavior

• Request body:

{
  "licenseToken": "string",
  "authContext": "string"
}

• When called, the API:
  • Marks the session as ended for this license and authContext.
  • Immediately “frees” the license so another machine can call activate without waiting for the 10‑minute timeout.
• Response is typically 204 No Content on success.

Example client flow

• When the user logs out or exits the application:
  1. Call POST /licensing/deactivate with licenseToken and the current authContext.
  2. Stop any scheduled extend calls.
  3. Clear any local session state.

If the app closes unexpectedly and deactivate is never called, the license will still be released automatically once the 10‑minute session window elapses.

Why Not Just Use validate?

You can technically build your own “session” concept around licensing/validate by storing timestamps on the client and stopping when too much time passes. However, doing so has several downsides:

• No server-side concurrency control: The backend cannot reliably know which machine “owns” the session, so you can’t strictly prevent parallel use.
• Weaker misuse detection: Background jobs can still detect long-term misuse, but they don’t enforce a strict “only one active session right now” rule.
• No unified audit trail: Session lifecycle events (started, extended, ended) are much easier to reason about when you use dedicated endpoints.

Session-based endpoints solve these problems by:

• Enforcing one active session per license at any given time.
• Allowing multiple machines over time as long as they don’t overlap (activate/deactivate/extend).
• Providing a clear, explicit contract for clients:
  • activate → start session
  • extend → keep it alive
  • deactivate → end it immediately

Use validate when you just need to know “is this license ok?” at a point in time.
Use activate / extend / deactivate when you need session-based control to prevent concurrent usage while still supporting flexible, sequential device usage.