License Key Management with Creem

Welcome to Creem’s License Key documentation! As a Merchant of Record specializing in Micro-SaaS and AI Businesses, we’ve built a powerful license key system that’s both flexible and secure.

Getting Started

Setting up license keys for your product is straightforward:

Configuring
- Create a new product with a License key feature enabled
- Configure settings related to the licenses
- Set up your product integration or payment links for customer purchases
Dealing with a license after purchases
- Enable the user to enter a license key in your application
- Activate a license key instance
- Validate a license key instance on subsequent usages

Step-by-Step Tutorial: Implementing License Keys

Let’s walk through the complete process of implementing license keys in your application. We’ll cover everything from initial setup to handling customer interactions.

Step 1: Creating Your Product

First, let’s set up your product in the Creem dashboard:

Navigate to Products: Log into your Creem dashboard and click “Create New Product”
Enable License Keys: In the product settings, enable the “License Key Management” feature
Configure License Settings:
- Set activation limits (e.g., 3 devices per license)
- Define expiration periods (e.g., 1 year from purchase)

Step 2: Customer Purchase Flow

When a customer purchases your product, here’s what happens automatically:

A unique license key is generated and associated with their purchase
The key appears in their order confirmation page
It’s included in their email receipt
The key is accessible in their customer portal

Activating Licenses

The activation endpoint is used to register a new device or instance with a valid license key. This is typically done when a user first sets up your application.

Common Use Cases

Initial Software Setup: When users first install your application and enter their license key
Device Migration: When users need to activate your software on a new device
Multi-device Scenarios: For users who need to use your software across multiple machines
Cloud Instance Deployment: When spinning up new cloud instances that require license validation

Benefits of the Activation System

Prevents Unauthorized Usage: Each activation is tracked and counted against the license limit
User Flexibility: Allows users to manage their own device activations within their quota
Usage Analytics: Provides insights into how and where your software is being used
Fraud Prevention: Helps identify and prevent license key sharing or abuse

Activation Flow

Here’s how a typical activation flow works:

User purchases your software and receives a license key
User installs your application on their device
Application prompts for license key during first launch
Application generates a unique instance name (usually based on device characteristics)
Activation request is sent to the API
Upon successful activation, the instance ID is stored locally for future validation

Endpoint Details

URL: https://test-api.creem.io/v1/licenses/activate
Method: POST
Authentication: Requires API key in headers

Request Parameters

key (required): The license key to activate
instance_name (required): A unique identifier for the device/installation

The InstanceName field is an arbitrary name of your choice. Merchants usually use the internal customer ID, or customer email for quality of life maintainability.

Response Format

{
  "id": "<string>",
  "mode": "test",
  "object": "<string>",
  "status": "active",
  "key": "ABC123-XYZ456-XYZ456-XYZ456",
  "activation": 5,
  "activation_limit": 1,
  "expires_at": "2023-09-13T00:00:00Z",
  "created_at": "2023-09-13T00:00:00Z",
  "instance": [
    {
      "id": "<string>",
      "mode": "test",
      "object": "license-instance",
      "name": "My Customer License Instance",
      "status": "active",
      "created_at": "2023-09-13T00:00:00Z"
    }
  ]
}

Implementation Examples

import { createCreem } from "creem_io";

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: true,
});

const license = await creem.licenses.activate({
  key: "ABC123-XYZ456-XYZ456-XYZ456",
  instanceName: "johns-macbook-pro",
});

Pro Implementation Tips

Use the TypeScript SDK for automatic type safety and better error handling
Generate meaningful instance names that help users identify their devices
Store activation tokens securely using system keychains or encrypted storage
Implement automatic retry logic for failed activation attempts
Add clear user feedback for activation status and remaining device quota

Validating Licenses

The validation endpoint allows you to verify if a license key is still valid and active. This is crucial for maintaining software security and ensuring proper usage of your product.

Key Validation Features

Real-time Status: Get immediate feedback on license validity
Feature Access: Check which features are enabled for the license
Quota Management: Track remaining usage quotas
Expiration Checking: Verify if the license is still within its valid period

When to Validate

To ensure continued valid usage, implement regular license checks:

Validate on application startup
Check before accessing premium features
Periodically verify license status (e.g., daily)
Handle network errors and retry scenarios appropriately

Validation Flow

Here’s how the validation process typically works:

Application starts up or performs periodic check
Retrieves stored license key and instance ID
Sends validation request to Creem API
Processes response and updates application state
Handles any validation errors or expired licenses

Endpoint Details

URL: https://test-api.creem.io/v1/licenses/validate
Method: POST
Authentication: Requires API key in headers

Request Parameters

key (required): The license key to validate
instance_id (required): The instance ID received during activation

Response Format

{
  "id": "<string>",
  "mode": "test",
  "object": "<string>",
  "status": "active",
  "key": "ABC123-XYZ456-XYZ456-XYZ456",
  "activation": 5,
  "activation_limit": 1,
  "expires_at": "2023-09-13T00:00:00Z",
  "created_at": "2023-09-13T00:00:00Z",
  "instance": [
    {
      "id": "<string>",
      "mode": "test",
      "object": "license-instance",
      "name": "My Customer License Instance",
      "status": "active",
      "created_at": "2023-09-13T00:00:00Z"
    }
  ]
}

Implementation Examples

import { createCreem } from "creem_io";

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: true,
});

const validatedLicense = await creem.licenses.validate({
  key: "ABC123-XYZ456-XYZ456-XYZ456",
  instanceId: "inst_xyz123",
});

console.log(validatedLicense.status); // "active" | "inactive" | "expired" | "disabled"

if (validatedLicense.status === "active") {
  // Grant access to premium features
  console.log(`License expires at: ${validatedLicense.expiresAt}`);
} else {
  // Deny access or show upgrade prompt
  console.log("License is not active");
}

Implementation Best Practices

Cache validation results locally to reduce API calls
Implement graceful degradation for offline scenarios
Add clear user feedback for validation status
Keep logs of validation attempts for troubleshooting

Deactivating Licenses

The deactivation endpoint allows you to remove a device’s access to a license key. This is essential for managing device transfers, subscription cancellations, and maintaining security of your software.

Key Deactivation Features

Instance Management: Remove specific device instances from active licenses
Activation Slot Recovery: Free up slots for new device activations
Usage Tracking: Monitor deactivation history and remaining slots
Automatic Cleanup: Clear associated device data upon deactivation

Common Deactivation Scenarios

There are several scenarios where you might need to deactivate a license:

User requests to transfer their license to a new device
Subscription cancellation
Suspicious activity detection
User switching between devices

Deactivation Flow

Here’s how the deactivation process typically works:

User initiates deactivation (e.g., switching devices)
Application retrieves stored license key and instance ID
Sends deactivation request to Creem API
Cleans up local license data
Provides feedback to user about deactivation status

Endpoint Details

URL: https://test-api.creem.io/v1/licenses/deactivate
Method: POST
Authentication: Requires API key in headers

Request Parameters

key (required): The license key to deactivate
instance_id (required): The instance ID to deactivate

Response Format

{
  "id": "<string>",
  "mode": "test",
  "object": "<string>",
  "status": "active",
  "key": "ABC123-XYZ456-XYZ456-XYZ456",
  "activation": 5,
  "activation_limit": 1,
  "expires_at": "2023-09-13T00:00:00Z",
  "created_at": "2023-09-13T00:00:00Z",
  "instance": [
    {
      "id": "<string>",
      "mode": "test",
      "object": "license-instance",
      "name": "My Customer License Instance",
      "status": "active",
      "created_at": "2023-09-13T00:00:00Z"
    }
  ]
}

Implementation Examples

import { createCreem } from "creem_io";

const creem = createCreem({
  apiKey: process.env.CREEM_API_KEY!,
  testMode: true,
});

const deactivatedLicense = await creem.licenses.deactivate({
  key: "ABC123-XYZ456-XYZ456-XYZ456",
  instanceId: "inst_xyz123",
});

Deactivation Best Practices

Always confirm deactivation with users before proceeding
Clear all local license data after successful deactivation
Implement proper error handling for failed deactivations
Maintain deactivation logs for customer support

Error Handling

Common error responses across all license endpoints include:

400 Bad Request: Invalid or missing parameters
401 Unauthorized: Invalid API key
403 Forbidden: License key has reached activation limit (activation only)
404 Not Found: Invalid license key or instance ID
409 Conflict: Instance already deactivated (deactivation only)
410 Gone: License has been revoked or expired (validation only)

Best Practices

Security: Store the instance_id securely after successful activation
Error Handling: Implement graceful error handling for network issues
User Experience: Add clear user feedback for all license-related actions
Offline Support: Consider implementing an offline grace period
Validation: Always validate license keys on startup and critical operations
Caching: Cache validation results to prevent excessive API calls
API Keys: Securely store API keys and never expose them client-side

Common Pitfalls to Avoid

Don’t store API keys in client-side code
Never expose the full license validation logic to end users
Don’t forget to handle edge cases (expired licenses, network errors)

Security Considerations

Creem’s license key system implements several security measures:

Encrypted communication channels
Automatic suspicious activity detection
Regular security audits and updates

API Reference

For detailed API documentation, visit:

License Key API Reference

TypeScript SDK Documentation

View the complete TypeScript SDK documentation with examples for licenses, subscriptions, and more.

Need Help?Our support team is ready to assist you with license key implementation. Contact us at support@creem.io

Get Started

Features

Code

Integrations

Merchant of Record

For Customers

​License Key Management with Creem

​Getting Started

​Step-by-Step Tutorial: Implementing License Keys

​Step 1: Creating Your Product

​Step 2: Customer Purchase Flow

​Activating Licenses

​Common Use Cases

​Benefits of the Activation System

​Activation Flow

​Endpoint Details

​Request Parameters

​Response Format

​Implementation Examples

​Validating Licenses

​Key Validation Features

​When to Validate

​Validation Flow

​Endpoint Details

​Request Parameters

​Response Format

​Implementation Examples

​Deactivating Licenses

​Key Deactivation Features

​Common Deactivation Scenarios

​Deactivation Flow

​Endpoint Details

​Request Parameters

​Response Format

​Implementation Examples

​Error Handling

​Best Practices

​Common Pitfalls to Avoid

​Security Considerations

​API Reference

TypeScript SDK Documentation

License Key Management with Creem

Getting Started

Step-by-Step Tutorial: Implementing License Keys

Step 1: Creating Your Product

Step 2: Customer Purchase Flow

Activating Licenses

Common Use Cases

Benefits of the Activation System

Activation Flow

Endpoint Details

Request Parameters

Response Format

Implementation Examples

Validating Licenses

Key Validation Features

When to Validate

Validation Flow

Endpoint Details

Request Parameters

Response Format

Implementation Examples

Deactivating Licenses

Key Deactivation Features

Common Deactivation Scenarios

Deactivation Flow

Endpoint Details

Request Parameters

Response Format

Implementation Examples

Error Handling

Best Practices

Common Pitfalls to Avoid

Security Considerations

API Reference