Skip to main content

​
Overview

This guide will walk you through setting up KeyBox and integrating it into your application. You’ll create your first client, project, and license, then validate it using the SDK of your choice.
Time required: 10-15 minutesWhat you’ll need:
  • Access to a KeyBox dashboard instance
  • Node.js 18+, Python 3.10+, or .NET 8.0+
  • Basic knowledge of your chosen language/framework

​
Step 1: Dashboard Setup

First, you’ll need to set up your client, project, and license in the KeyBox dashboard.
1

Create an Account

Navigate to your KeyBox dashboard and create an account. After signing up, you’ll be redirected to the main dashboard.
If you’re self-hosting KeyBox, make sure you’ve deployed both the backend API and frontend dashboard. See Deployment Guide for details.
2

Create a Client

Clients represent your customers or end users who will receive licenses.
  1. Click Clients in the sidebar
  2. Click Add Client
  3. Enter the following details:
    • Name: Your customer’s name (e.g., “Acme Corp”)
    • Email: Customer’s email address
  4. Click Create
Each client can have multiple projects and licenses associated with them.
3

Create a Project

Projects represent the products or services you’re licensing (e.g., “Enterprise API”, “Desktop App Pro”).
  1. Click Projects in the sidebar
  2. Click Add Project
  3. Enter the following details:
    • Project Name: Name of your product (e.g., “MyApp Enterprise”)
    • Client: Select the client you just created
  4. Click Create
4

Generate a License

Now create a license key for your client’s project.
  1. Click Licenses in the sidebar
  2. Click Create License
  3. Configure the license:
    • Client: Select your client
    • Project: Select the project you created
    • Duration: Choose duration (1-12 months)
    • Services: Add any service identifiers (optional)
  4. Click Generate License
Copy the license key immediately! You’ll need it to integrate with your application. The key will look like: kb_xxxxxxxxxxxxxxxxxxxxx
The license will be created in PENDING state and will activate when first used.

​
Step 2: Choose Your SDK

Select the SDK that matches your application’s language and framework:
Perfect for Express APIs, Next.js applications, and Node.js CLIs.Requirements:
  • Node.js 18 or higher
  • Express.js (for web apps)

​
Step 3: Install the SDK

Install the KeyBox SDK for your chosen language: 
npm install keybox-sdk

​
Step 4: Integrate the SDK

Add license protection to your application with just a few lines of code: 
import express from 'express';
import { protectNodeApp } from 'keybox-sdk';

const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Hello from licensed app!' });
});

// Protect your app with KeyBox
await protectNodeApp({
  app,
  port: 3000,
  productName: 'MyApp Enterprise',
  key: process.env.LICENSE_KEY
});

console.log('✓ App is protected and running on http://localhost:3000');
Security best practice: Never hardcode license keys in your source code. Use environment variables:
  • Node.js: process.env.LICENSE_KEY
  • Python: os.getenv("LICENSE_KEY")
  • .NET: builder.Configuration["LICENSE_KEY"]

​
Step 5: Set Environment Variables

Create a .env file in your project root to store the license key securely: 
LICENSE_KEY=kb_xxxxxxxxxxxxxxxxxxxxx
PORT=3000
Then load the environment variables in your application: 
import dotenv from 'dotenv';
dotenv.config();

// Now you can use process.env.LICENSE_KEY

​
Step 6: Test Your Integration

Now let’s verify that everything is working correctly.
1

Start your application

Run your application using your normal start command:
node index.js
You should see logs indicating successful license activation:
[2026-03-05T10:30:00.000Z] [KEYBOX] [INFO] Activating license {"productName":"MyApp Enterprise"}
[2026-03-05T10:30:01.000Z] [KEYBOX] [INFO] License activated
[2026-03-05T10:30:01.200Z] [KEYBOX] [INFO] License daemon started {"intervalSeconds":900}
2

Verify license activation

Check your KeyBox dashboard:
  1. Navigate to Licenses
  2. Find your license in the list
  3. Verify the status changed from PENDING to ACTIVE
  4. Check that a Machine ID is now displayed
The machine ID binds this license to the specific device where it was activated. This prevents unauthorized license sharing.
3

Test your API endpoint

Make a request to your application to verify it’s running:
curl http://localhost:3000
You should receive a successful response from your protected application!

​
What Happens Next?

Your application is now protected by KeyBox! Here’s what’s happening behind the scenes:
1

Automatic validation

The SDK automatically validates the license every 15 minutes in the background.
2

License monitoring

The validation daemon checks if the license is:
  • Still in ACTIVE state
  • Not expired
  • Not revoked
3

Automatic shutdown

If the license becomes invalid (expired or revoked), the SDK will:
  1. Log an error message
  2. Stop accepting new requests
  3. Gracefully shut down your application
  4. Exit the process
License enforcement: If you revoke or expire a license in the dashboard, the customer’s application will automatically shut down within 15 minutes.

​
Testing License Revocation

To see license revocation in action:
1

Keep your application running

Leave your application running in one terminal window.
2

Revoke the license

In your KeyBox dashboard:
  1. Go to Licenses
  2. Find your test license
  3. Click the Revoke button
  4. Confirm the action
3

Watch the logs

Within 15 minutes, you’ll see logs indicating license revocation:
[2026-03-05T10:45:00.000Z] [KEYBOX] [ERROR] License REVOKED — shutting down
[2026-03-05T10:45:01.000Z] [KEYBOX] [INFO] Server closed gracefully
Your application will automatically shut down.

​
Advanced Integration Examples

​
Example 1: Custom Error Handling

Handle license errors gracefully with custom error messages: 
import express from 'express';
import { activateLicense, startLicenseDaemon } from 'keybox-sdk';

const app = express();

app.get('/', (req, res) => {
  res.json({ message: 'Licensed app running' });
});

// Activate license with error handling
try {
  await activateLicense({
    productName: 'MyApp',
    key: process.env.LICENSE_KEY
  });
  console.log('✓ License activated successfully');
} catch (error) {
  console.error('✗ License activation failed:', error.message);
  console.error('Please contact support for a valid license.');
  process.exit(1);
}

// Start server
const server = app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

// Start license monitoring
await startLicenseDaemon({
  productName: 'MyApp',
  key: process.env.LICENSE_KEY,
  onRevoke: (data) => {
    console.error('\n⚠ LICENSE REVOKED');
    console.error(`Reason: ${data.status}`);
    console.error('Application will now shut down.\n');
    
    server.close(() => {
      console.log('Server closed');
      process.exit(1);
    });
  }
});

​
Example 2: Self-Hosted KeyBox

If you’re self-hosting KeyBox, specify your custom API URL: 
await protectNodeApp({
  app,
  port: 3000,
  productName: 'MyApp',
  key: process.env.LICENSE_KEY,
  apiUrl: 'https://keybox.yourcompany.com' // Your custom URL
});

​
Troubleshooting

​
”License activation failed”

Verify that:
  • The license key is correctly copied (no extra spaces)
  • The environment variable is loaded correctly
  • The key starts with kb_
The productName parameter must exactly match the project name in your dashboard (case-sensitive).Example: If your project is named “MyApp Enterprise”, use:
productName: 'MyApp Enterprise'  // ✓ Correct
productName: 'myapp enterprise'  // ✗ Wrong - case mismatch
Ensure your application can reach the KeyBox API:
curl https://api-keybox.vercel.app/validate
If you’re behind a firewall or proxy, make sure outbound HTTPS connections are allowed.
In your dashboard, verify the license is:
  • Not expired
  • Not revoked
  • In PENDING or ACTIVE state

​
”License server did not return JSON”

This error indicates a network or connectivity issue:
  1. Check the API URL - Make sure you’re using the correct endpoint
  2. Verify network access - Ensure your app can make HTTPS requests
  3. Check for proxy issues - Corporate proxies may intercept requests
  4. Self-hosted users - Verify your backend is running and accessible

​
App doesn’t shut down when license is revoked

  1. Wait for validation cycle - Changes take effect within 15 minutes
  2. Check logs - Look for validation errors in your console
  3. Verify revocation - Ensure the license shows as REVOKED in dashboard
  4. Restart if needed - Force restart to trigger immediate validation

​
Next Steps

Congratulations! You’ve successfully integrated KeyBox into your application. Here’s what to explore next:

Core Concepts

Learn how KeyBox works under the hood

Dashboard Guide

Master the KeyBox dashboard features

SDK Documentation

Dive deeper into SDK capabilities

API Reference

Explore the complete API documentation

​
Need Help?

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and share ideas

Build docs developers (and LLMs) love

Get started for freeTalk to us