Hiphops.io Hiphops logo - casey

Licensing quickstart

Create your first licensed product and issue a customer key in under 5 minutes.

Creating your first product

  1. Navigate to Products in your project dashboard
  2. Click Create product
  3. Enter a product name (letters, numbers, underscore only)
  4. Add a description for internal reference

Adding license fields

License fields collect customer-specific information. Common examples:

  • Company: Organization name
  • Users: Number of licensed users
  • Features: Enabled feature set
  • Expiry: License expiration date

Note: Email, Name, and Notes are preconfigured fields available for all products.

To add custom fields:

  1. Click Add field in the License fields section
  2. Choose field type (text, email, number, select, checkbox, date)
  3. Set field name and description
  4. Mark as required if needed
  5. Set default values for non-editable fields

Setting registry permissions

Grant customers access to Docker images:

  1. In the Pull roles section, click Add role
  2. Select from existing pull roles (or use the default pull role)
  3. This allows customers to pull images using their product key

Save your product

Click Save product to create your licensable product template.

Issue your first product key

  1. From the Products list, click Create new key for your product
  2. Fill in the customer’s license field values
  3. Add customer email and name for identification
  4. Click Create customer

Share credentials with customer

Two options for sharing:

  • Click Share onboarding link
  • Copy the generated URL and send to customer
  • Customer can view documentation and download credentials
  • Link expires in 7 days

Option 2: Manual sharing

  • Click Share manually
  • Copy the JWT token
  • Send token directly to customer
  • Customer uses token for authentication

Customer usage

Your customer can now authenticate with their product key:

# Login to registry
docker login your-project.ctr.dev -u customer -p <jwt-token>

# Pull licensed images
docker pull your-project.ctr.dev/your-app:latest

The JWT token serves as both license proof and registry authentication credential.

Adding license validation to your app

To integrate license checking into your application, see the Integration guide for detailed setup instructions.

Quick example

import { license } from "@hiphops/hook";

const info = await license();
if (!info.verified) {
  console.error("License validation failed:", info.verify_failures);
  process.exit(1); // Exit application if license is invalid
}

// Access license fields
const maxUsers = info.license.seats; // Access the 'seats' field
console.log(`License valid for ${maxUsers} users`);

Important: Your application should decide what to do if license validation fails - typically this means refusing to start or disabling features.