Skip to content

API Reference

Jump to bottom
VetheonGames edited this page Sep 20, 2025 · 1 revision

API Reference

Complete REST API documentation for Source-License platform integration, license validation, and system management.

🌟 Overview

Source-License provides a comprehensive REST API for integrating license validation, order processing, and system management into your applications. The API supports JSON responses, JWT authentication, and webhooks for real-time notifications.

Base URL

Production: https://yourdomain.com/api
Development: http://localhost:4567/api

API Versioning

Current API version: v1 (implicit in all endpoints)

🔐 Authentication

JWT Token Authentication

Most API endpoints require JWT authentication. Obtain a token using the authentication endpoint:

Get Authentication Token

Endpoint: POST /api/auth

Request:

POST /api/auth
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "your_password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2024-01-15T15:30:00Z",
  "user": {
    "email": "admin@example.com",
    "role": "admin"
  }
}

Using Authentication Token

Include the JWT token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key Authentication (Alternative)

For server-to-server integration, you can use API keys:

Header:

X-API-Key: your_api_key_here

📋 License Management API

License Validation

Validate License Key

Endpoint: GET /api/license/{license_key}/validate

Parameters:

  • license_key (string): The license key to validate

Response:

{
  "valid": true,
  "status": "active",
  "product": {
    "id": 1,
    "name": "My Software Pro",
    "version": "1.0.0"
  },
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "expires_at": "2025-12-31T23:59:59Z",
    "activations_used": 1,
    "max_activations": 3,
    "customer_email": "customer@example.com"
  },
  "validation_timestamp": "2024-01-15T10:30:00Z"
}

Error Response (Invalid License):

{
  "valid": false,
  "error": "license_not_found",
  "message": "License key not found or invalid"
}

Error Response (Expired License):

{
  "valid": false,
  "error": "license_expired",
  "message": "License has expired",
  "expired_at": "2024-01-01T00:00:00Z"
}

Validate with Machine Check

Endpoint: GET /api/license/{license_key}/validate?machine_fingerprint={fingerprint}

Parameters:

  • license_key (string): The license key to validate
  • machine_fingerprint (string): Unique machine identifier

Response:

{
  "valid": true,
  "status": "active",
  "machine_authorized": true,
  "activation_details": {
    "machine_fingerprint": "unique_machine_id",
    "activated_at": "2024-01-10T14:20:00Z",
    "ip_address": "192.168.1.100"
  },
  "product": {
    "id": 1,
    "name": "My Software Pro"
  },
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "expires_at": "2025-12-31T23:59:59Z",
    "activations_used": 1,
    "max_activations": 3
  }
}

License Activation

Activate License

Endpoint: POST /api/license/{license_key}/activate

Request:

POST /api/license/XXXX-XXXX-XXXX-XXXX/activate
Content-Type: application/json

{
  "machine_fingerprint": "unique_machine_id",
  "machine_name": "John's MacBook Pro",
  "system_info": {
    "os": "macOS 14.0",
    "processor": "Apple M2",
    "memory": "16GB",
    "platform": "arm64"
  },
  "application_info": {
    "version": "1.0.0",
    "build": "1234"
  }
}

Response (Success):

{
  "success": true,
  "activation_id": "12345",
  "message": "License activated successfully",
  "activation_details": {
    "machine_fingerprint": "unique_machine_id",
    "activated_at": "2024-01-15T10:30:00Z",
    "ip_address": "192.168.1.100"
  },
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "activations_used": 2,
    "max_activations": 3,
    "remaining_activations": 1
  }
}

Response (Activation Limit Reached):

{
  "success": false,
  "error": "activation_limit_reached",
  "message": "Maximum number of activations reached",
  "license": {
    "activations_used": 3,
    "max_activations": 3
  }
}

Deactivate License

Endpoint: POST /api/license/{license_key}/deactivate

Request:

POST /api/license/XXXX-XXXX-XXXX-XXXX/deactivate
Content-Type: application/json

{
  "machine_fingerprint": "unique_machine_id"
}

Response:

{
  "success": true,
  "message": "License deactivated successfully",
  "license": {
    "activations_used": 1,
    "max_activations": 3,
    "remaining_activations": 2
  }
}

License Information

Get License Details

Endpoint: GET /api/license/{license_key}

Authentication: Required

Response:

{
  "license": {
    "key": "XXXX-XXXX-XXXX-XXXX",
    "status": "active",
    "created_at": "2024-01-01T00:00:00Z",
    "expires_at": "2025-12-31T23:59:59Z",
    "activations_used": 1,
    "max_activations": 3,
    "customer_email": "customer@example.com"
  },
  "product": {
    "id": 1,
    "name": "My Software Pro",
    "description": "Professional software license",
    "version": "1.0.0"
  },
  "activations": [
    {
      "id": 1,
      "machine_fingerprint": "unique_machine_id",
      "machine_name": "John's MacBook Pro",
      "activated_at": "2024-01-10T14:20:00Z",
      "ip_address": "192.168.1.100",
      "system_info": {
        "os": "macOS 14.0",
        "processor": "Apple M2"
      }
    }
  ]
}

🛒 Order Management API

Order Creation

Create Order

Endpoint: POST /api/orders

Request:

POST /api/orders
Content-Type: application/json

{
  "customer_email": "customer@example.com",
  "items": [
    {
      "product_id": 1,
      "quantity": 1
    }
  ],
  "billing_info": {
    "name": "John Doe",
    "company": "Acme Corp",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  }
}

Response:

{
  "order": {
    "id": "12345",
    "status": "pending",
    "customer_email": "customer@example.com",
    "subtotal": 99.00,
    "tax_total": 8.91,
    "total": 107.91,
    "currency": "USD",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "items": [
    {
      "product_id": 1,
      "product_name": "My Software Pro",
      "quantity": 1,
      "unit_price": 99.00,
      "total": 99.00
    }
  ],
  "payment_url": "https://checkout.stripe.com/pay/cs_...",
  "payment_methods": ["stripe", "paypal"]
}

Process Free Order

Endpoint: POST /api/orders/free

Request:

POST /api/orders/free
Content-Type: application/json

{
  "customer_email": "customer@example.com",
  "items": [
    {
      "product_id": 2,
      "quantity": 1
    }
  ]
}

Response:

{
  "order": {
    "id": "12346",
    "status": "completed",
    "customer_email": "customer@example.com",
    "total": 0.00,
    "currency": "USD"
  },
  "licenses": [
    {
      "key": "YYYY-YYYY-YYYY-YYYY",
      "product_name": "Free Trial License",
      "expires_at": "2024-02-15T00:00:00Z"
    }
  ]
}

Order Status

Get Order Details

Endpoint: GET /api/orders/{order_id}

Authentication: Required

Response:

{
  "order": {
    "id": "12345",
    "status": "completed",
    "customer_email": "customer@example.com",
    "subtotal": 99.00,
    "tax_total": 8.91,
    "total": 107.91,
    "currency": "USD",
    "payment_method": "stripe",
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:00Z"
  },
  "items": [
    {
      "product_id": 1,
      "product_name": "My Software Pro",
      "quantity": 1,
      "unit_price": 99.00,
      "total": 99.00
    }
  ],
  "licenses": [
    {
      "key": "XXXX-XXXX-XXXX-XXXX",
      "product_name": "My Software Pro",
      "expires_at": "2025-12-31T23:59:59Z",
      "download_url": "https://yourdomain.com/download/secure_token"
    }
  ],
  "payment_details": {
    "transaction_id": "pi_1234567890",
    "payment_method": "visa",
    "last4": "1234"
  }
}

📦 Product API

Product Catalog

List Products

Endpoint: GET /api/products

Parameters:

  • status (optional): Filter by status (active, inactive)
  • category (optional): Filter by category
  • limit (optional): Number of results (default: 50)
  • offset (optional): Pagination offset

Response:

{
  "products": [
    {
      "id": 1,
      "name": "My Software Pro",
      "description": "Professional software license",
      "price": 99.00,
      "currency": "USD",
      "license_type": "one_time",
      "max_activations": 3,
      "trial_period_days": 30,
      "features": [
        "Advanced features",
        "Priority support",
        "Free updates"
      ],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Get Product Details

Endpoint: GET /api/products/{product_id}

Response:

{
  "product": {
    "id": 1,
    "name": "My Software Pro",
    "description": "Professional software license with advanced features",
    "price": 99.00,
    "currency": "USD",
    "license_type": "one_time",
    "max_activations": 3,
    "license_duration_days": null,
    "trial_period_days": 30,
    "setup_fee": 0.00,
    "features": [
      "Advanced reporting",
      "API access",
      "Priority support",
      "Custom integrations"
    ],
    "download_info": {
      "has_download": true,
      "file_size": "45.2 MB",
      "supported_platforms": ["Windows", "macOS", "Linux"]
    },
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-10T00:00:00Z"
  }
}

⚙️ Settings API

Configuration Management

Get Settings Category

Endpoint: GET /api/settings/{category}

Authentication: Required (Admin only)

Categories: app, license, payment, email, tax, security

Example: GET /api/settings/license

Response:

{
  "category": "license",
  "settings": {
    "default_license_format": "XXXX-XXXX-XXXX-XXXX",
    "default_max_activations": 3,
    "auto_generate_on_purchase": true,
    "email_delivery_enabled": true,
    "license_expiry_notification_days": 30
  }
}

Update Setting

Endpoint: PUT /api/settings/{category}/{key}

Authentication: Required (Admin only)

Request:

PUT /api/settings/license/default_max_activations
Content-Type: application/json

{
  "value": 5
}

Response:

{
  "success": true,
  "setting": {
    "category": "license",
    "key": "default_max_activations",
    "value": 5,
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

🔔 Webhook Endpoints

Payment Webhooks

Stripe Webhook

Endpoint: POST /api/webhook/stripe

Headers:

Stripe-Signature: t=1234567890,v1=signature_here

Supported Events:

  • payment_intent.succeeded: Payment completed successfully
  • payment_intent.payment_failed: Payment failed
  • invoice.payment_succeeded: Subscription payment successful
  • customer.subscription.updated: Subscription status changed

PayPal Webhook

Endpoint: POST /api/webhook/paypal

Supported Events:

  • PAYMENT.CAPTURE.COMPLETED: Payment completed
  • PAYMENT.CAPTURE.DENIED: Payment denied
  • BILLING.SUBSCRIPTION.ACTIVATED: Subscription activated

📊 Analytics API

License Analytics

License Usage Statistics

Endpoint: GET /api/analytics/licenses

Authentication: Required (Admin only)

Parameters:

  • period (optional): day, week, month, year (default: month)
  • product_id (optional): Filter by product

Response:

{
  "period": "month",
  "data": {
    "total_licenses": 1250,
    "active_licenses": 1100,
    "expired_licenses": 150,
    "activation_rate": 88.0,
    "average_activations_per_license": 2.3
  },
  "trends": {
    "new_licenses": 45,
    "new_activations": 89,
    "license_growth_rate": 3.6
  }
}

Revenue Analytics

Revenue Statistics

Endpoint: GET /api/analytics/revenue

Authentication: Required (Admin only)

Response:

{
  "period": "month",
  "data": {
    "total_revenue": 12500.00,
    "orders_count": 125,
    "average_order_value": 100.00,
    "recurring_revenue": 2500.00
  },
  "trends": {
    "revenue_growth": 15.2,
    "order_growth": 8.5
  },
  "top_products": [
    {
      "product_id": 1,
      "name": "My Software Pro",
      "revenue": 7500.00,
      "orders": 75
    }
  ]
}

🔒 Error Handling

HTTP Status Codes

The API uses standard HTTP status codes:

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate license key)
  • 422 Unprocessable Entity: Validation errors
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "Invalid input parameters",
    "details": {
      "email": ["must be a valid email address"],
      "product_id": ["must be a valid product ID"]
    }
  },
  "request_id": "req_1234567890"
}

Common Error Codes

Code Description
authentication_required Valid authentication token required
invalid_token JWT token is invalid or expired
insufficient_permissions User lacks required permissions
license_not_found License key not found
license_expired License has expired
activation_limit_reached Maximum activations exceeded
product_not_found Product ID not found
order_not_found Order ID not found
validation_error Request validation failed
payment_processing_error Payment could not be processed
rate_limit_exceeded Too many requests

🚀 Rate Limiting

The API implements rate limiting to ensure fair usage:

Rate Limits

Endpoint Type Limit Window
Authentication 10 requests 1 minute
License Validation 1000 requests 1 hour
License Operations 100 requests 1 hour
Order Creation 50 requests 1 hour
Admin API 500 requests 1 hour

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642678800

📝 SDK Examples

cURL Examples

Validate License

curl -X GET "https://yourdomain.com/api/license/XXXX-XXXX-XXXX-XXXX/validate" \
  -H "Content-Type: application/json"

Activate License

curl -X POST "https://yourdomain.com/api/license/XXXX-XXXX-XXXX-XXXX/activate" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_fingerprint": "unique_machine_id",
    "system_info": {
      "os": "Windows 11",
      "processor": "Intel i7"
    }
  }'

JavaScript/Node.js Example

const axios = require('axios');

class SourceLicenseAPI {
  constructor(baseURL, apiKey = null) {
    this.baseURL = baseURL;
    this.apiKey = apiKey;
  }

  async validateLicense(licenseKey) {
    try {
      const response = await axios.get(
        `${this.baseURL}/api/license/${licenseKey}/validate`
      );
      return response.data;
    } catch (error) {
      throw new Error(`License validation failed: ${error.response.data.error.message}`);
    }
  }

  async activateLicense(licenseKey, machineFingerprint, systemInfo = {}) {
    try {
      const response = await axios.post(
        `${this.baseURL}/api/license/${licenseKey}/activate`,
        {
          machine_fingerprint: machineFingerprint,
          system_info: systemInfo
        }
      );
      return response.data;
    } catch (error) {
      throw new Error(`License activation failed: ${error.response.data.error.message}`);
    }
  }
}

// Usage
const api = new SourceLicenseAPI('https://yourdomain.com');
const result = await api.validateLicense('XXXX-XXXX-XXXX-XXXX');
console.log('License valid:', result.valid);

Python Example

import requests

class SourceLicenseAPI:
    def __init__(self, base_url, api_key=None):
        self.base_url = base_url
        self.api_key = api_key
        self.session = requests.Session()
        
        if api_key:
            self.session.headers.update({'X-API-Key': api_key})

    def validate_license(self, license_key):
        """Validate a license key"""
        response = self.session.get(
            f"{self.base_url}/api/license/{license_key}/validate"
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            response.raise_for_status()

    def activate_license(self, license_key, machine_fingerprint, system_info=None):
        """Activate a license on a machine"""
        data = {
            'machine_fingerprint': machine_fingerprint,
            'system_info': system_info or {}
        }
        
        response = self.session.post(
            f"{self.base_url}/api/license/{license_key}/activate",
            json=data
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            response.raise_for_status()

# Usage
api = SourceLicenseAPI('https://yourdomain.com')
result = api.validate_license('XXXX-XXXX-XXXX-XXXX')
print(f"License valid: {result['valid']}")

🧪 Testing

Test Environment

Use the sandbox environment for testing:

Base URL: https://sandbox.yourdomain.com/api

Test License Keys

The following test license keys are available in sandbox mode:

  • TEST-VALID-LICENSE-KEY: Valid active license
  • TEST-EXPIRED-LICENSE: Expired license for testing
  • TEST-MAXED-ACTIVATIONS: License with maximum activations reached

This API reference provides complete documentation for integrating with Source-License. For additional support or questions, please refer to the Troubleshooting Guide or submit an issue on GitHub.

Clone this wiki locally