License Management

Activates a new license for the IPCom system using a provided license key. This endpoint allows administrators to update or activate system licenses.

Request

POST /api/license

Authentication Required: Must include JWT token in Authorization header.

Required Scope: license

Content-Type: application/json

Request Body

{
  "key": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789012345678901234567890abcdef"
}

Parameters:

• key (string, required): The license key to activate (hexadecimal string, variable length)

Request Examples

Activate License Key

curl -X POST "http://your-server-ip:port/api/license" \
     -H "Authorization: Bearer YOUR_JWT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"key": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789012345678901234567890abcdef"}'

Using JavaScript

const response = await fetch('/api/license', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    key: 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789012345678901234567890abcdef'
  })
});

Response

Success (200 OK)

{
  "success": true
}

Error Responses

Note: Error responses are returned as plain text, not JSON.

400 Bad Request

Invalid request body

License activation failed

401 Unauthorized

NOT_LOGGED_IN

403 Forbidden

FORBIDDEN

405 Method Not Allowed

Method Not Allowed

Critical Application Behavior

⚠️ IPCom Application Shutdown Warning

IMPORTANT: When a valid license is successfully applied, the IPCom application will automatically shut down. This is an application shutdown, not an operating system shutdown.

Auto-Restart Behavior

• Manual Application: The IPCom application will NOT restart automatically unless configured as a system service
• System Service: If IPCom is configured as a Windows service or systemd service with auto-restart enabled, the application will restart automatically

Service Configuration Examples

Windows Service (Auto-Restart)

sc create IPComService binPath="C:\IPCom\ipcom.exe" start=auto
sc config IPComService failure= restart/60000/restart/60000/restart/60000

systemd Service (Linux Auto-Restart)

[Unit]
Description=IPCom Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ipcom
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

License Management

License Activation Process

1. Validation: System validates the provided license key format
2. Activation: License key is processed and activated
3. Configuration Update: License information is saved to system configuration
4. Application Shutdown: IPCom application automatically shuts down to apply license changes
5. Manual Restart Required: Administrator must restart the IPCom application manually (unless service configured)

License Key Format

License keys are hexadecimal strings with variable length:

• Format: Hexadecimal string (no dashes or separators)
• Characters: Hexadecimal digits (0-9, A-F)

Usage Examples

Basic License Activation

async function activateLicense(token, licenseKey) {
  try {
    console.log('Activating license...');
    
    const response = await fetch('/api/license', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        key: licenseKey
      })
    });
    
    if (!response.ok) {
      const errorText = await response.text();
      throw new Error(`License activation failed: ${errorText}`);
    }
    
    const result = await response.json();
    console.log('✓ License activated successfully');
    console.log('⚠ IMPORTANT: IPCom application will shut down now');
    console.log('⚠ Manual restart required unless service is configured');
    
    return result;
  } catch (error) {
    console.error('✗ License activation failed:', error);
    throw error;
  }
}

Service Configuration Helpers

// Windows Service Configuration Helper
function generateWindowsServiceCommands(ipcomPath) {
  return {
    create: `sc create IPComService binPath="${ipcomPath}" start=auto`,
    configure: `sc config IPComService failure= restart/60000/restart/60000/restart/60000`,
    start: `sc start IPComService`,
    stop: `sc stop IPComService`,
    delete: `sc delete IPComService`
  };
}

// systemd Service Configuration Helper
function generateSystemdServiceFile(ipcomPath) {
  return `[Unit]
Description=IPCom License Service
After=network.target

[Service]
Type=simple
ExecStart=${ipcomPath}
Restart=always
RestartSec=10
User=ipcom
Group=ipcom

[Install]
WantedBy=multi-user.target`;
}

// Docker Compose Configuration Helper
function generateDockerComposeConfig() {
  return `version: '3.8'
services:
  ipcom:
    image: ipcom:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    environment:
      - IPCOM_CONFIG_FILE=/app/config/config.json`;
}

Security Considerations

License Scope Protection

The license scope should be highly restricted:

// Recommended user configuration for license management
{
  "id": 1,
  "login": "license_admin", 
  "password": "secure_password",
  "scopes": ["license"],  // Only license scope
  "token_time": 60        // Short token lifetime for security
}

Audit Logging

async function auditLicenseActivation(licenseKey, result, user) {
  const auditEntry = {
    timestamp: new Date().toISOString(),
    action: 'license_activation',
    licenseKey: maskLicenseKey(licenseKey),
    success: result.success,
    user: user,
    ipAddress: getClientIP(),
    userAgent: getUserAgent()
  };
  
  // Log to security audit system
  await logSecurityEvent('LICENSE_ACTIVATION', auditEntry);
  
  // Alert administrators
  if (result.success) {
    await sendAlert('LICENSE_ACTIVATED', `License activated by ${user}`);
  }
}

Best Practices

• Restrict Access: Only assign license scope to administrators who need it
• Short Tokens: Use short-lived tokens for license operations
• Audit Trail: Log all license activation attempts (success and failure)
• Service Configuration: Always configure IPCom as a system service for production
• Backup Configuration: Backup current configuration before license changes
• Testing Environment: Test license activation in development environment first