Skip to main content

​
Overview

The create license endpoint generates a new license key associated with a specific client and project. This is an authenticated endpoint that requires a valid JWT token.

​
Endpoint

POST /license/create
This endpoint requires authentication. Include a valid JWT token in the Authorization header.

​
Authentication

Include the JWT token in the Authorization header: 
Authorization: Bearer <your-jwt-token>

​
Request

​
Request Body

​
duration
number
required
License duration in months (1-12)
​
clientId
string
required
MongoDB ObjectId of the client
​
projectId
string
required
MongoDB ObjectId of the project
​
services
array
Array of services included in the license (e.g., [“Hosting”, “Domain”]). Defaults to [“Hosting”] if not provided.

​
Example Request

curl -X POST https://your-keybox-server.com/license/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "duration": 12,
    "clientId": "60f7b3b3e6b3a72e8c8e4a1a",
    "projectId": "60f7b3b3e6b3a72e8c8e4a1b",
    "services": ["Hosting", "Domain"]
  }'

​
Response

​
Success Response

​
message
string
Success message
​
license
object
The created license object

​
Example Response

{
  "message": "License created",
  "license": {
    "key": "KB-60f7b3b3e6b3a72e8c8e4a1b-A1B2-C3D4-E5F6",
    "duration": 12,
    "issuedAt": "2024-01-01T00:00:00.000Z",
    "expiresAt": "2025-01-01T00:00:00.000Z",
    "status": "PENDING",
    "services": ["Hosting", "Domain"],
    "user": "60f7b3b3e6b3a72e8c8e4a1a",
    "client": "60f7b3b3e6b3a72e8c8e4a1a",
    "project": "60f7b3b3e6b3a72e8c8e4a1b",
    "_id": "60f7b3b3e6b3a72e8c8e4a1c"
  }
}

​
License Key Format

License keys are automatically generated using this format: 
KB-{projectId}-{random}-{random}-{random}
  • KB: KeyBox prefix
  • projectId: The project’s MongoDB ObjectId
  • random segments: Three random alphanumeric segments for uniqueness
Example: KB-60f7b3b3e6b3a72e8c8e4a1b-A1B2-C3D4-E5F6

​
License Status

All newly created licenses start with status PENDING:
  • PENDING: License created but not yet activated
  • ACTIVE: License activated on a machine (requires activation endpoint)
  • EXPIRED: License duration has elapsed
  • REVOKED: License manually revoked by developer
Licenses must be activated using the activate endpoint before they can be used.

​
Services

The services field defines what services are included in the license. Available options:
  • Hosting: Web hosting service
  • Domain: Domain registration/management
You can include multiple services in a single license: 
{
  "services": ["Hosting", "Domain"]
}
If not specified, defaults to ["Hosting"].

​
Error Responses

​
Invalid Duration

Status Code: 400 
{
  "message": "Invalid duration"
}
Duration must be between 1 and 12 months.

​
Missing Client or Project

Status Code: 400 
{
  "message": "Client & Project required"
}

​
Unauthorized

Status Code: 401 
{
  "message": "No token provided"
}

​
Server Error

Status Code: 500 
{
  "error": "Detailed error message"
}

​
Complete Example

Here’s a complete workflow for creating a license: 
class LicenseManager {
  constructor(serverUrl, authToken) {
    this.serverUrl = serverUrl;
    this.authToken = authToken;
  }

  async createLicense(clientId, projectId, duration, services = ['Hosting']) {
    try {
      const response = await fetch(`${this.serverUrl}/license/create`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${this.authToken}`
        },
        body: JSON.stringify({
          duration,
          clientId,
          projectId,
          services
        })
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      const data = await response.json();
      console.log('License created:', data.license.key);
      console.log('Status:', data.license.status);
      console.log('Expires:', new Date(data.license.expiresAt));
      
      return data.license;
    } catch (error) {
      console.error('Failed to create license:', error);
      throw error;
    }
  }
}

// Usage
const manager = new LicenseManager(
  'https://your-keybox-server.com',
  'your-jwt-token'
);

const license = await manager.createLicense(
  '60f7b3b3e6b3a72e8c8e4a1a', // clientId
  '60f7b3b3e6b3a72e8c8e4a1b', // projectId
  12, // duration in months
  ['Hosting', 'Domain'] // services
);

console.log('Share this key with your client:', license.key);

​
Best Practices

Validate Input

Validate client and project IDs exist before creating licenses

Reasonable Duration

Set appropriate license durations based on your business model

Track Services

Use the services field to clearly define what’s included

Store Keys Securely

Securely store and distribute license keys to clients

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us