Skip to main content

​
What is KeyBox?

KeyBox is a self-hosted license key management platform that helps you generate, validate, and revoke access to your software applications. It provides a complete solution for protecting your software with machine-bound licenses, real-time validation, and automated lifecycle management.
KeyBox is open-source and built with modern technologies including Node.js, Next.js, MongoDB, and Redis for optimal performance and scalability.

​
Why Use KeyBox?

KeyBox solves the complex challenge of software licensing by providing:

Secure License Generation

Generate cryptographically secure license keys tied to your projects and clients

Real-time Validation

Validate licenses in milliseconds with Redis caching layer

Machine Binding

Lock licenses to specific machines to prevent unauthorized sharing

Automated Management

Background daemons handle validation, expiration, and revocation automatically

​
Perfect For

  • SaaS Platforms - Control access with time-based subscriptions
  • Desktop Applications - Protect software with machine-locked licenses
  • API Services - Manage access to your APIs and microservices
  • Enterprise Software - Deploy licensed software to corporate clients
  • Developer Tools - Monetize CLI tools and development frameworks

​
Key Features

​
License Management

KeyBox provides comprehensive license lifecycle management:
  • Generate unique license keys with configurable durations (1-12 months)
  • Activate licenses on first use with machine binding
  • Validate licenses with automatic status checks every 15 minutes
  • Revoke licenses instantly when needed
  • Expire licenses automatically based on configured duration

​
License States

Every license in KeyBox has one of four states:
StateDescription
PENDINGLicense created but not yet activated
ACTIVELicense activated and currently valid
EXPIREDLicense duration has ended
REVOKEDLicense manually revoked by admin

​
Multi-Language SDK Support

Integrate KeyBox into your application with official SDKs: 
import { protectNodeApp } from "keybox-sdk"

await protectNodeApp({
  app,
  port: 3000,
  productName: "MyApp",
  key: process.env.LICENSE_KEY
})

​
Background Validation Daemon

All SDKs include a background validation daemon that:
  • Validates the license on application startup
  • Re-validates every 15 minutes automatically
  • Gracefully shuts down your app if license becomes invalid
  • Handles network errors without disrupting operation
If a license is revoked or expires, the background daemon will automatically shut down your application to prevent unauthorized use.

​
Architecture Overview

KeyBox consists of three main components:

​
Components

1

Backend API

Node.js/Express server that handles:
  • License generation and validation
  • Client and project management
  • Authentication with JWT and OAuth
  • Redis caching for fast validation
Location: apps/server/
2

Frontend Dashboard

Next.js web application for:
  • Managing clients and projects
  • Creating and monitoring licenses
  • Viewing usage analytics
  • Accessing API documentation
Location: apps/web/
3

SDKs

Official SDKs for integrating KeyBox into your applications:
  • Node.js SDK - For Express and Node.js apps
  • Python SDK - For FastAPI and Python apps
  • .NET SDK - For ASP.NET Core apps
Location: apps/SDK/

​
How It Works

1

Create a Client

Register your customer in the KeyBox dashboard with their name and email
2

Create a Project

Add a project for the client (e.g., “MyApp Pro”, “Enterprise Edition”)
3

Generate License

Create a license key with:
  • Duration (1-12 months)
  • Services included
  • Project association
The license starts in PENDING state
4

Integrate SDK

Add the KeyBox SDK to your application and pass the license key
5

Activate on First Run

When the app starts, the SDK:
  • Activates the license (changes state to ACTIVE)
  • Binds it to the machine ID
  • Starts the background validation daemon
6

Continuous Validation

The daemon validates the license every 15 minutes:
  • Checks if still ACTIVE
  • Verifies not expired
  • Confirms not revoked
  • Shuts down app if invalid

​
Data Models

​
License Schema

interface License {
  key: string              // Unique license key
  duration: number         // Duration in months (1-12)
  issuedAt: Date          // Activation timestamp
  expiresAt: Date         // Expiration timestamp
  status: Status          // PENDING | ACTIVE | EXPIRED | REVOKED
  services: string[]      // Included services
  machineId: string       // Bound machine identifier
  user: ObjectId          // License owner
  client: ObjectId        // Associated client
  project: ObjectId       // Associated project
}

​
Client Schema

interface Client {
  name: string            // Client name
  email: string           // Client email
  owner: ObjectId         // User who created this client
  createdAt: Date        // Creation timestamp
}

​
Project Schema

interface Project {
  name: string            // Project name
  client: ObjectId        // Associated client
  createdAt: Date        // Creation timestamp
}

​
API Endpoints

KeyBox provides RESTful API endpoints for all operations:
EndpointMethodDescription
/validatePOSTValidate a license key
/validate/activatePOSTActivate a pending license
/license/createPOSTCreate a new license
/license/toggle/:keyPATCHToggle license status (active/revoked)
/clientGET/POSTManage clients
/projectGET/POSTManage projects
See the API Reference for detailed endpoint documentation.

​
Security Features

Machine Binding

Licenses are bound to unique machine IDs to prevent sharing across devices

JWT Authentication

All API requests require valid JWT tokens for authentication

Redis Caching

Validated licenses are cached to prevent database overload and ensure fast response times

Rate Limiting

API endpoints are rate-limited to prevent abuse

​
Performance

  • Validation Speed: < 10ms (with Redis cache)
  • Cache Duration: Configurable TTL
  • Background Checks: Every 15 minutes
  • Database: MongoDB with indexed queries

​
Tech Stack

Backend:
  • Node.js 18+
  • Express.js
  • TypeScript
  • MongoDB (Mongoose)
  • Redis
  • JWT Authentication
Frontend:
  • Next.js 14
  • React
  • TypeScript
  • Tailwind CSS
SDKs:
  • Node.js (CommonJS)
  • Python 3.10+
  • .NET 8.0+

​
What’s Next?

Quick Start Guide

Get KeyBox up and running in 5 minutes

How It Works

Dive deeper into KeyBox architecture

SDK Integration

Learn how to integrate KeyBox into your app

Deploy KeyBox

Self-host KeyBox on your infrastructure

Build docs developers (and LLMs) love

Get started for freeTalk to us