License Server responses

License Server Response Guide #

This document provides a comprehensive guide to all possible responses from the Barkoder License Server based on different license states, overload conditions, and expiry scenarios.

Response Structure #

All license validation responses follow this encrypted JSON structure:

                {
  "lt": "T|D|P",           // License Type (Trial, Development, Production)
  "ld": 0|1,               // License Decoders (0=denied, >0=allowed decoders)
  "li": 12345,             // License ID
  "t": 1640995200,         // Client timestamp
  "st": 1640995201,        // Server timestamp
  "sv": "1.0.0",           // SDK Version
  "kv": "1.0",             // Key Version
  "tt": "B|S|O|D",         // Tracking Type (Bi Directional, Standard, One Direction, Disabled)
  "pl": 0|63,              // Platform List (0=denied, >0=allowed platforms)
  "pa": 255,               // Parsers Mask
  "lb": "BA|BD|U",         // License Bound (Bound to App, Bound to Device, Unbound)
  "exp": "2024-12-31",     // Expiry Date
  "c": 86400               // Check frequency in seconds
}

Key Response Fields #

ld (License Decoders): 0 = Access Denied, >0 = Access Granted
pl (Platform List): 0 = Access Denied, >0 = Access Granted
tt (Tracking Type):
B = Bi Directional (device reports back to server)
S = Standard (normal tracking)
O = One Direction (device doesn't report back)
D = Disabled (no tracking)
Status Array: Internal tracking of license state progression

License States #

1. Valid License (GREEN) #

Condition: License is active, not expired, within device limits

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "GREEN"]
}

2. App ID Mismatch (Bound License) #

Condition: Device app ID doesn't match license configuration

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED"]
}

3. Blacklisted App #

Condition: App ID is on the blacklist

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED"]
}

4. Canceled SPR #

Condition: Subscription/SPR has been canceled

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED", "CANCELED"]
}

Overload Scenarios #

Standard Overload Flow #

1. Pre-Overload (Within Buffer) #

Condition: Usage ≤ allowed_devices × (1 + buffer_percentage)

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "GREEN"]
}

Example: 10 devices allowed, 20% buffer → up to 12 devices = GREEN

2. Overload Detection (Grace Period Active) #

Condition: Usage > buffer limit, within grace period

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "OVERLOAD"]
}

Details:

All devices (new and existing) are allowed
Grace period typically 7 days
Overload event recorded

3. Post-Grace Period (Standard Overload) #

Condition: Grace period expired, overload < 100%

Existing Devices (first_allow = GREEN):

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "OVERLOAD"]
}

New Devices (device_event = CREATE):

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED", "MAXED"]
}

4. Critical Overload (≥100% Over Limit) #

Condition: Usage ≥ 2 × allowed_devices (ignores grace period)

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED", "MAXED"]
}

Details:

ALL devices denied immediately
No grace period
No grandfathering of existing devices

Monitor-Only License Override #

Condition: License has monitor=1, ignores device limits

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "OVERLOAD"]
}

Note: Monitor-only licenses allow access regardless of overload state

Expiry Scenarios #

Standard Expiry Flow #

1. Active License #

Condition: Current date < expiry_date

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "exp": "2024-12-31",
  "status": ["ALLOWED", "GREEN"]
}

2. Expired (Within Grace Period) #

Condition: expiry_date < current_date < deny_date

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "exp": "2024-12-31",
  "status": ["ALLOWED", "EXPIRED"]
}

Details:

License expired but still functional
Grace period active (typically 7-30 days)
Access maintained during grace

3. Ended (Grace Period Expired) #

Condition: current_date ≥ deny_date

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "exp": "2024-12-31",
  "status": ["DENIED", "ENDED"]
}

Per-Device Trial Licenses #

1. New Device Activation #

Condition: Per-device license, first activation

                {
  "lt": "T",
  "ld": 255,
  "pl": 63,
  "exp": "2024-01-30",
  "status": ["ALLOWED", "GREEN"]
}

Details:

Device gets individual trial period (default 30 days)
Trial starts from device creation date
Device marked as verified immediately

2. Existing Device (Trial Active) #

Condition: Device trial period not expired

                {
  "lt": "T",
  "ld": 255,
  "pl": 63,
  "exp": "2024-01-30",
  "status": ["ALLOWED", "GREEN"]
}

3. Device Trial Expired #

Condition: Device-specific trial period ended

                {
  "lt": "T",
  "ld": 0,
  "pl": 0,
  "exp": "2024-01-30",
  "status": ["DENIED", "ENDED"]
}

Combined Scenarios #

1. Expired + Overloaded (Grace Period Active) #

Condition: License expired AND overloaded, both grace periods active

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "EXPIRED", "OVERLOAD"]
}

2. Expired + Maxed #

Condition: License expired AND device limit exceeded post-grace

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED", "EXPIRED", "MAXED"]
}

3. Ended + Overloaded #

Condition: License ended (grace expired) AND overloaded

                {
  "lt": "P",
  "ld": 0,
  "pl": 0,
  "status": ["DENIED", "ENDED", "OVERLOAD"]
}

4. Monitor-Only + Any State #

Condition: Monitor license overrides most restrictions

                {
  "lt": "P",
  "ld": 255,
  "pl": 63,
  "status": ["ALLOWED", "EXPIRED", "MAXED"]
}

Note: Monitor licenses allow access even when expired/maxed

Status Codes Reference #

Primary Status #

ALLOWED: Access granted
DENIED: Access denied

License State #

GREEN: Normal operation
EXPIRED: License past expiry date (grace period may be active)
ENDED: License expired and grace period ended
CANCELED: SPR/subscription canceled

Device State #

OVERLOAD: Device usage exceeded allowed limits
MAXED: Device limits exceeded and grace period ended

Special Cases #

MISMATCH: App ID doesn't match license configuration
BLACKLISTED: App ID is blacklisted

Response Examples #

Example 1: Normal Operation #

Example 2: Overloaded with Grace Period #

Example 3: Denied - New Device on Maxed License #

Integration Guidelines #

Client-Side Handling #

Check ld and pl values: If either is 0, access is denied
Monitor exp field: Warn users of upcoming expiry
Handle denials gracefully: Implement fallback behavior
Respect c (check frequency): Don't exceed check intervals

Common Patterns #

                // Basic access check
if (response.ld > 0 && response.pl > 0) {
  // Access granted
  enableFeatures(response.ld, response.pl);
} else {
  // Access denied
  disableFeatures();
  showAccessDeniedMessage();
}

// Expiry warning
const expiryDate = new Date(response.exp);
const daysUntilExpiry = Math.ceil((expiryDate - new Date()) / (1000 * 60 * 60 * 24));
if (daysUntilExpiry <= 7 && daysUntilExpiry > 0) {
  showExpiryWarning(daysUntilExpiry);
}

Last Updated: January 2025

Version: 1.0.0

License Server responses

License Server Response Guide #

Response Structure #

Key Response Fields #

License States #

1. Valid License (GREEN) #

2. App ID Mismatch (Bound License) #

3. Blacklisted App #

4. Canceled SPR #

Overload Scenarios #

Standard Overload Flow #

1. Pre-Overload (Within Buffer) #

2. Overload Detection (Grace Period Active) #

3. Post-Grace Period (Standard Overload) #

4. Critical Overload (≥100% Over Limit) #

Monitor-Only License Override #

Expiry Scenarios #

Standard Expiry Flow #

1. Active License #

2. Expired (Within Grace Period) #

3. Ended (Grace Period Expired) #

Per-Device Trial Licenses #

1. New Device Activation #

2. Existing Device (Trial Active) #

3. Device Trial Expired #

Combined Scenarios #

1. Expired + Overloaded (Grace Period Active) #

2. Expired + Maxed #

3. Ended + Overloaded #

4. Monitor-Only + Any State #

Status Codes Reference #

Primary Status #

License State #

Device State #

Special Cases #

Response Examples #

Example 1: Normal Operation #

Example 2: Overloaded with Grace Period #

Example 3: Denied - New Device on Maxed License #

Integration Guidelines #

Client-Side Handling #

Common Patterns #

Page Contents