API Reference

Complete documentation for the CyberLicense v1 REST API. All API endpoints return JSON responses and use standard HTTP status codes.

📋 Table of Contents

Base URL
Authentication
License API
Customer API
Products API
Audit Log API
Export API
2FA API
Automated Actions API
BuiltByBit Integration API
Webhooks API
Error Handling
Rate Limiting

Base URL

All API endpoints are prefixed with /api:

http://localhost:3000/api

Note: The API does not use versioning (no /v1 prefix). All endpoints are directly under /api.

Authentication

Admin Authentication

Admin APIs require authentication via Discord OAuth session. After logging in through the web interface, a session cookie is created and used for subsequent API requests.

Session Requirements:

Valid Discord OAuth session
Admin user must be registered in the database
Session expires after 24 hours (configurable)

Customer Authentication

Customer APIs require authentication via Discord OAuth session. Customers log in through the customer portal, and their session is used for API requests.

Public API Authentication

Some endpoints (like license validation) are public and don't require authentication. However, they may be subject to rate limiting.

JWT Tokens (Optional)

For programmatic access, you can use JWT tokens. Configure JWT in config.yml and use the token in the Authorization header:

Authorization: Bearer <jwt-token>

License API

Endpoints for license management and validation.

POST `/api/license/validate`

Validates a software license. This is the primary endpoint for license validation in your applications.

Authentication: None (public endpoint, but rate limited)

Request Body:

{
  "key": "LIC-ABC123-XYZ789",
  "ip": "192.168.1.1", // Optional: IP address of the client
  "hwid": "HWID-123456" // Optional: Hardware ID of the client
}

Success Response (200):

{
  "success": true,
  "valid": true,
  "license": {
    "key": "LIC-ABC123-XYZ789",
    "active": true,
    "expiresAt": "2024-12-31T23:59:59.000Z",
    "ipLimit": 1,
    "hwidLimit": 1,
    "usedIps": ["192.168.1.1"],
    "usedHwids": ["HWID-123456"],
    "licenseType": "fixed"
  }
}

Error Response (400/403):

{
  "success": false,
  "valid": false,
  "error": "License not found" | "License expired" | "License suspended" | "IP limit exceeded" | "HWID limit exceeded" | "License revoked"
}

Possible Error Messages:

"License not found" - The license key doesn't exist
"License expired" - The license has expired
"License suspended" - The license is suspended
"License revoked" - The license has been revoked
"IP limit exceeded" - Too many IP addresses are using this license
"HWID limit exceeded" - Too many hardware IDs are using this license
"License not active" - The license is not active

Rate Limit: Configurable in config.yml (default: 200 requests per 15 minutes)

Example Usage:

curl -X POST http://localhost:3000/api/license/validate \
  -H "Content-Type: application/json" \
  -d '{
    "key": "LIC-ABC123-XYZ789",
    "ip": "192.168.1.1",
    "hwid": "HWID-123456"
  }'

POST `/api/license/rotate`

Rotates a license key (generates a new key for an existing license). The old key becomes invalid.

Authentication: Admin only

Request Body:

{
  "key": "LIC-ABC123-XYZ789"
}

Response (200):

{
  "success": true,
  "oldKey": "LIC-ABC123-XYZ789",
  "newKey": "LIC-DEF456-UVW012"
}

Error Response (404):

{
  "success": false,
  "error": "License not found"
}

POST `/api/license/clear`

Clears IP/HWID usage restrictions for a license. This allows the license to be used from new IP addresses and hardware IDs.

Authentication: Admin only

Request Body:

{
  "key": "LIC-ABC123-XYZ789"
}

Response (200):

{
  "success": true,
  "message": "License restrictions cleared"
}

Error Response (404):

{
  "success": false,
  "error": "License not found"
}

Customer API

Endpoints for customer self-service portal. Customers can view their licenses, usage statistics, and manage their account.

Base URL: /api/customer

Authentication: Customer session (Discord OAuth)

GET `/api/customer/licenses/:licenseId`

Gets all licenses for the authenticated customer.

Response (200):

{
  "success": true,
  "licenses": [
    {
      "_id": "...",
      "key": "LIC-ABC123",
      "product": {
        "_id": "...",
        "name": "My Product"
      },
      "active": true,
      "expiresAt": "2024-12-31T23:59:59.000Z",
      "licenseType": "fixed",
      "ipLimit": 1,
      "hwidLimit": 1,
      "usedIps": ["192.168.1.1"],
      "usedHwids": ["HWID-123456"]
    }
  ]
}

Gets detailed information about a specific license for the authenticated customer.

Response (200):

{
  "success": true,
  "license": {
    "_id": "...",
    "key": "LIC-ABC123",
    "product": {
      "_id": "...",
      "name": "My Product",
      "description": "Product description"
    },
    "active": true,
    "expiresAt": "2024-12-31T23:59:59.000Z",
    "licenseType": "fixed",
    "usageStats": {
      "totalRequests": 150,
      "successfulRequests": 145,
      "blockedRequests": 5,
      "lastUsed": "2024-01-15T10:30:00.000Z",
      "uniqueIPs": 3,
      "uniqueHWIDs": 2
    }
  }
}

Error Response (404):

{
  "success": false,
  "error": "License not found"
}

GET `/api/customer/licenses/:licenseId/usage`

Gets usage statistics for a license.

Query Parameters:

startDate (string, optional): Start date in ISO 8601 format
endDate (string, optional): End date in ISO 8601 format

Response (200):

{
  "success": true,
  "usage": {
    "total": 150,
    "byStatus": {
      "success": 145,
      "blocked": 5,
      "invalid": 0
    },
    "dailyStats": {
      "2024-01-01": {
        "success": 10,
        "blocked": 0,
        "invalid": 0
      }
    },
    "requests": [
      {
        "_id": "...",
        "ipAddress": "192.168.1.1",
        "hwid": "HWID-123456",
        "status": "success",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

GET `/api/customer/licenses/stats`

Gets general license statistics for the authenticated customer.

Response (200):

{
  "success": true,
  "stats": {
    "totalLicenses": 5,
    "activeLicenses": 3,
    "expiredLicenses": 1,
    "suspendedLicenses": 1,
    "totalRequests": 500,
    "successfulRequests": 480,
    "byType": {
      "fixed": 3,
      "trial": 1,
      "consumption": 1,
      "enterprise": 0
    }
  }
}

GET `/api/customer/licenses/:licenseId/credits`

Gets credit balance for a consumption-based license.

Response (200):

{
  "success": true,
  "credits": {
    "total": 1000,
    "used": 350,
    "remaining": 650
  }
}

Error Response (400):

{
  "success": false,
  "error": "License is not a consumption-based license"
}

Products API

Endpoints for product management. Products represent software products or applications that licenses are issued for.

Base URL: /api/products

Authentication: Admin only

GET `/api/products`

Gets all products.

Query Parameters:

includeCounts (boolean, optional): Include license counts for each product (default: false)
activeOnly (boolean, optional): Return only active products (default: false)

Response (200):

{
  "success": true,
  "products": [
    {
      "_id": "...",
      "name": "My Product",
      "description": "Product description",
      "isActive": true,
      "licensePrefix": "LIC",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "count": 1
}

Response with counts (200):

When includeCounts=true:

{
  "success": true,
  "products": [
    {
      "_id": "...",
      "name": "My Product",
      "description": "Product description",
      "isActive": true,
      "licensePrefix": "LIC",
      "licenseCount": 10,
      "activeLicenseCount": 8,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "count": 1
}

Error Response (401):

{
  "success": false,
  "error": "Unauthorized"
}

Example Usage:

# Get all products
curl -X GET http://localhost:3000/api/products \
  -H "Cookie: connect.sid=..."

# Get all products with license counts
curl -X GET "http://localhost:3000/api/products?includeCounts=true" \
  -H "Cookie: connect.sid=..."

# Get only active products with counts
curl -X GET "http://localhost:3000/api/products?activeOnly=true&includeCounts=true" \
  -H "Cookie: connect.sid=..."

GET `/api/products/:id`

Gets a single product by ID.

Query Parameters:

includeCounts (boolean, optional): Include license counts for the product (default: false)

Response (200):

{
  "success": true,
  "product": {
    "_id": "...",
    "name": "My Product",
    "description": "Product description",
    "isActive": true,
    "licensePrefix": "LIC",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Response with counts (200):

When includeCounts=true:

{
  "success": true,
  "product": {
    "_id": "...",
    "name": "My Product",
    "description": "Product description",
    "isActive": true,
    "licensePrefix": "LIC",
    "licenseCount": 10,
    "activeLicenseCount": 8,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

Error Response (401):

{
  "success": false,
  "error": "Unauthorized"
}

Error Response (404):

{
  "success": false,
  "error": "Product not found"
}

Example Usage:

# Get product by ID
curl -X GET http://localhost:3000/api/products/507f1f77bcf86cd799439011 \
  -H "Cookie: connect.sid=..."

# Get product with license counts
curl -X GET "http://localhost:3000/api/products/507f1f77bcf86cd799439011?includeCounts=true" \
  -H "Cookie: connect.sid=..."

Audit Log API

Endpoints to view system audit logs. All administrative actions are automatically logged.

Base URL: /api/audit

Authentication: Admin only

GET `/api/audit`

Gets audit logs with optional filters.

Query Parameters:

userId (string, optional): Filter by admin user ID
resourceType (string, optional): Filter by resource type (license, customer, product, admin, transaction, notification, system)
resourceId (string, optional): Filter by resource ID
action (string, optional): Filter by action (create, update, delete, view, login, logout, export, import, revoke, activate, suspend)
startDate (string, optional): Start date in ISO 8601 format
endDate (string, optional): End date in ISO 8601 format
success (boolean, optional): Filter by success status
limit (number, optional): Number of results (default: 100, max: 1000)
skip (number, optional): Skip results for pagination (default: 0)

Response (200):

{
  "success": true,
  "auditLogs": [
    {
      "_id": "...",
      "userId": "...",
      "action": "create",
      "resourceType": "license",
      "resourceId": "...",
      "changes": {
        "before": {},
        "after": {
          "key": "LIC-123",
          "active": true
        }
      },
      "ip": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "success": true,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "count": 150,
  "total": 150
}

GET `/api/audit/:id`

Gets a single audit log entry by ID.

Response (200):

{
  "success": true,
  "auditLog": {
    "_id": "...",
    "userId": "...",
    "action": "create",
    "resourceType": "license",
    "resourceId": "...",
    "changes": {
      "before": {},
      "after": { ... }
    },
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "success": true,
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Export API

Endpoints to export data in CSV and PDF formats.

Base URL: /api/export

Authentication: Admin only

GET `/api/export/licenses/csv`

Exports licenses in CSV format.

Query Parameters:

product (string, optional): Filter by product ID
customer (string, optional): Filter by customer ID
active (boolean, optional): Filter by active status
licenseType (string, optional): Filter by type (fixed, trial, consumption, enterprise)

Response: Downloadable CSV file

Headers:

Content-Type: text/csv
Content-Disposition: attachment; filename=licenses-{timestamp}.csv

Example:

curl -X GET "http://localhost:3000/api/export/licenses/csv?active=true" \
  -H "Cookie: session=..." \
  -o licenses.csv

GET `/api/export/licenses/pdf`

Exports licenses in PDF format.

Query Parameters: Same as CSV export

Response: Downloadable PDF file

Headers:

Content-Type: application/pdf
Content-Disposition: attachment; filename=licenses-{timestamp}.pdf

GET `/api/export/transactions/csv`

Exports transactions in CSV format.

Query Parameters:

customer (string, optional): Filter by customer ID
status (string, optional): Filter by status (pending, processing, completed, failed, refunded, cancelled)
startDate (string, optional): Start date in ISO 8601 format
endDate (string, optional): End date in ISO 8601 format

Response: Downloadable CSV file

GET `/api/export/summary/pdf`

Exports a summary report in PDF format with general statistics.

Response: Downloadable PDF file

2FA API

Endpoints for two-factor authentication management.

Base URL: /api/2fa

Authentication: Admin only

GET `/api/2fa/setup`

Generates a secret and QR code for 2FA setup.

Response (200):

{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauthUrl": "otpauth://totp/CyberLicense:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=CyberLicense",
  "qrCode": "data:image/png;base64,..."
}

Usage:

Display the QR code to the user
User scans with Google Authenticator, Authy, or any TOTP app
User enters the token to verify with /api/2fa/enable

POST `/api/2fa/enable`

Enables 2FA after token verification.

Request Body:

{
  "token": "123456"
}

Response (200):

{
  "success": true,
  "backupCodes": ["ABC123", "DEF456", "GHI789", "JKL012", "MNO345"]
}

⚠️ Important: Save the backup codes in a secure location! They can be used to recover access if the 2FA device is lost.

Error Response (400):

{
  "success": false,
  "error": "Invalid token"
}

POST `/api/2fa/disable`

Disables 2FA for the current admin.

Request Body:

{
  "password": "admin-password" // Optional: May require password confirmation
}

Response (200):

{
  "success": true
}

POST `/api/2fa/verify`

Verifies a 2FA token or backup code during login.

Request Body:

{
  "token": "123456" // Or "backupCode": "ABC123"
}

Response (200):

{
  "success": true,
  "verified": true
}

Error Response (400):

{
  "success": false,
  "error": "Invalid token or backup code"
}

GET `/api/2fa/status`

Checks if 2FA is enabled for the current admin.

Response (200):

{
  "success": true,
  "enabled": true,
  "required": true // Whether 2FA is required for this admin
}

Automated Actions API

Endpoints for managing automated actions. Automated actions are triggered by events and can perform various tasks.

Base URL: /api/automated-actions

Authentication: Admin only

GET `/api/automated-actions`

Gets all automated actions.

Response (200):

{
  "success": true,
  "actions": [
    {
      "_id": "...",
      "name": "Auto-revoke on violations",
      "description": "Revokes license after 5 violations",
      "enabled": true,
      "trigger": {
        "event": "violation_threshold",
        "threshold": 5
      },
      "actions": [
        {
          "type": "revoke_license",
          "params": {}
        }
      ],
      "executionCount": 3,
      "lastExecutedAt": "2024-01-01T00:00:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET `/api/automated-actions/:id`

Gets a single automated action by ID.

Response (200):

{
  "success": true,
  "action": {
    "_id": "...",
    "name": "Auto-revoke on violations",
    "description": "Revokes license after 5 violations",
    "enabled": true,
    "trigger": { ... },
    "actions": [ ... ],
    "executionCount": 3,
    "lastExecutedAt": "2024-01-01T00:00:00.000Z"
  }
}

POST `/api/automated-actions`

Creates a new automated action.

Request Body:

{
  "name": "Auto-suspend expired licenses",
  "description": "Automatically suspends expired licenses",
  "enabled": true,
  "trigger": {
    "event": "license_expired",
    "conditions": {}
  },
  "actions": [
    {
      "type": "suspend_license",
      "params": {
        "reason": "License expired"
      }
    }
  ]
}

Response (201):

{
  "success": true,
  "action": {
    "_id": "...",
    "name": "Auto-suspend expired licenses",
    "description": "Automatically suspends expired licenses",
    "enabled": true,
    "trigger": { ... },
    "actions": [ ... ],
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Available Trigger Events:

license_created
license_expired
license_revoked
violation_threshold
anomaly_detected
transaction_completed
custom

Available Action Types:

revoke_license
suspend_license
send_notification
send_email
send_sms
send_telegram
create_license
update_license
webhook
custom

PUT `/api/automated-actions/:id`

Updates an automated action.

Request Body: Same fields as POST (all fields optional)

Response (200):

{
  "success": true,
  "action": {
    "_id": "...",
    "name": "Updated name",
    "description": "Updated description",
    "enabled": true,
    "trigger": { ... },
    "actions": [ ... ],
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

DELETE `/api/automated-actions/:id`

Deletes an automated action.

Response (200):

{
  "success": true
}

POST `/api/automated-actions/:id/execute`

Manually executes an automated action (for testing).

Request Body:

{
  "context": {
    "licenseKey": "LIC-ABC123",
    "event": "license_expired"
  }
}

Response (200):

{
  "success": true,
  "result": {
    "success": true,
    "results": [
      {
        "action": "suspend_license",
        "success": true,
        "message": "License suspended"
      }
    ]
  }
}

Webhooks

CyberLicense supports webhooks for external integrations. You can configure webhooks to be triggered by various events.

Webhook Configuration

Configure webhooks in config.yml:

webhooks:
  timeout: 5000 # milliseconds
  retries: 3
  events:
    - LICENSE_EXPIRED
    - NEW_REQUEST_BLOCKED
    - LICENSE_CREATED
    - LICENSE_REVOKED
    - ANOMALY_DETECTED

Available Events

LICENSE_EXPIRED - License expired
NEW_REQUEST_BLOCKED - License validation request blocked
LICENSE_CREATED - New license created
LICENSE_REVOKED - License revoked
ANOMALY_DETECTED - Suspicious activity detected
AUTOMATED_ACTION - Automated action executed

Webhook Format

When an event is triggered, CyberLicense sends a POST request to the configured webhook URL with the following format:

{
  "event": "LICENSE_EXPIRED",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "licenseKey": "LIC-ABC123",
    "expiresAt": "2024-01-01T00:00:00.000Z",
    "customerId": "...",
    "productId": "..."
  }
}

Webhook Security

Webhooks should be secured with:

HTTPS endpoints
Signature verification (optional, requires custom implementation)
IP whitelisting (if possible)

Error Handling

All API endpoints follow a consistent error response format.

Error Response Format

{
  "success": false,
  "error": "Error message"
}

Validation Errors

For validation errors, additional details may be provided:

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "key": "License key is required",
    "ip": "Invalid IP address format"
  }
}

HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request (validation error, invalid input)
401 - Unauthorized (authentication required)
403 - Forbidden (insufficient permissions)
404 - Not Found (resource doesn't exist)
429 - Too Many Requests (rate limit exceeded)
500 - Internal Server Error
503 - Service Unavailable (panic mode active)

Rate Limiting

All public API endpoints are subject to rate limiting to prevent abuse.

Default Rate Limits

Window: 15 minutes
Max Requests: 200 requests per window per IP

Configuration

Rate limiting can be configured in config.yml:

api:
  rateLimit:
    enabled: true
    windowMs: 900000 # 15 minutes in milliseconds
    max: 200 # Maximum requests per window

Rate Limit Headers

When a request is made, the following headers are included in the response:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Remaining requests in the current window
X-RateLimit-Reset - Unix timestamp when the rate limit resets

Rate Limit Exceeded

When the rate limit is exceeded, the API returns:

Status Code: 429 Too Many Requests

Response:

{
  "success": false,
  "error": "Too many requests, please try again later"
}

Support

For assistance or questions about the API:

Check the FAQ for common questions
Review the codebase for implementation details
Check the logs for error messages
Contact support through your preferred channel

Last Updated: 2025

📋 Table of Contents​

Base URL​

Authentication​

Admin Authentication​

Customer Authentication​

Public API Authentication​

JWT Tokens (Optional)​

License API​

POST /api/license/validate​

POST /api/license/rotate​

POST /api/license/clear​

Customer API​

GET /api/customer/licenses/:licenseId​

GET /api/customer/licenses/:licenseId/usage​

GET /api/customer/licenses/stats​

GET /api/customer/licenses/:licenseId/credits​

Products API​

GET /api/products​

GET /api/products/:id​

Audit Log API​

GET /api/audit​

GET /api/audit/:id​

Export API​

GET /api/export/licenses/csv​

GET /api/export/licenses/pdf​

GET /api/export/transactions/csv​

GET /api/export/summary/pdf​

2FA API​

GET /api/2fa/setup​

POST /api/2fa/enable​

POST /api/2fa/disable​

POST /api/2fa/verify​

GET /api/2fa/status​

Automated Actions API​

GET /api/automated-actions​

GET /api/automated-actions/:id​

POST /api/automated-actions​

PUT /api/automated-actions/:id​

DELETE /api/automated-actions/:id​

POST /api/automated-actions/:id/execute​

Webhooks​

Webhook Configuration​

Available Events​

Webhook Format​

Webhook Security​

Error Handling​

Error Response Format​

Validation Errors​

HTTP Status Codes​

Rate Limiting​

Default Rate Limits​

Configuration​

Rate Limit Headers​

Rate Limit Exceeded​

Support​

📋 Table of Contents

Base URL

Authentication

Admin Authentication

Customer Authentication

Public API Authentication

JWT Tokens (Optional)

License API

POST `/api/license/validate`

POST `/api/license/rotate`

POST `/api/license/clear`

Customer API

GET `/api/customer/licenses/:licenseId`

GET `/api/customer/licenses/:licenseId/usage`

GET `/api/customer/licenses/stats`

GET `/api/customer/licenses/:licenseId/credits`

Products API

GET `/api/products`

GET `/api/products/:id`

Audit Log API

GET `/api/audit`

GET `/api/audit/:id`

Export API

GET `/api/export/licenses/csv`

GET `/api/export/licenses/pdf`

GET `/api/export/transactions/csv`

GET `/api/export/summary/pdf`

2FA API

GET `/api/2fa/setup`

POST `/api/2fa/enable`

POST `/api/2fa/disable`

POST `/api/2fa/verify`

GET `/api/2fa/status`

Automated Actions API

GET `/api/automated-actions`

GET `/api/automated-actions/:id`

POST `/api/automated-actions`

PUT `/api/automated-actions/:id`

DELETE `/api/automated-actions/:id`

POST `/api/automated-actions/:id/execute`

Webhooks

Webhook Configuration

Available Events

Webhook Format

Webhook Security

Error Handling

Error Response Format

Validation Errors

HTTP Status Codes

Rate Limiting

Default Rate Limits

Configuration

Rate Limit Headers

Rate Limit Exceeded

Support