Overview

Kiwicodes License Manager validates software license seats using a secure, stateless request-signing model. Client applications do not request or refresh bearer tokens. Instead, every API request is signed with a public API key and a private shared secret.

Base URL

The SDK default base URL is:

https://licenseviewer.kiwicodes.com/api/

If your production API is deployed under a different Azure Functions hostname, set LicenseClientOptions.BaseUrl or replace the base URL in the direct HTTP examples.

Integration Options

Quick Start

Install the SDK

dotnet add package KCLicenseManager.Sdk

Minimal C# Usage

using KCLicenseManager.Sdk;
using KCLicenseManager.Sdk.Models;

using var client = new KiwicodesLicenseClient(new LicenseClientOptions
{
    ApiKey = "kc_pub_your_public_key",
    SharedSecret = "kc_sec_your_shared_secret",
    ProductCode = "Bonus Tools"
});

var result = await client.ActivateAsync(
    licenseKey: "ACT-KEY-123",
    hardwareId: "MACHINE-GUID-OR-STABLE-ID");

if (result.IsActive)
{
    Console.WriteLine($"License active. Seats: {result.CurrentSeats}/{result.MaxSeats}");

    // Check enabled features
    if (result.EnabledFeatures?.Contains("pro") == true)
        Console.WriteLine("Pro features unlocked.");

    // Check for updates
    if (result.LatestVersion is not null)
        Console.WriteLine($"Latest version available: {result.LatestVersion}");
}
else
{
    Console.WriteLine($"{result.Status}: {result.Description}");
}

Authentication Flow

Each request is self-authenticating. The client signs a canonical string containing a fixed signing prefix and the request date. The API validates the date, finds the subscription by API key, recomputes the signature with the stored shared secret, and compares signatures. The product code is sent alongside the signature in the Authorization header so the API can resolve the correct subscription context without requiring it in the request body.

Required Headers

Date: Wed, 06 May 2026 12:00:00 GMT
Authorization: algorithm="hmac-sha256",headers="date",signature="BASE64_SIGNATURE",apikey="kc_pub_your_public_key",productcode="Bonus Tools"

Signing String

kiwicodes-license
date: Wed, 06 May 2026 12:00:00 GMT

Signature Algorithm

1. Create a UTC date string in RFC 7231 format.
2. Build the signing string exactly as shown above, including the newline.
3. Compute HMAC-SHA256 using the shared secret as the key.
4. Base64 encode the binary HMAC result.
5. Send the public API key, product code, and signature in the Authorization header.

Authorization Header Format

The Authorization header contains five comma-separated key-value pairs:

.NET SDK Reference

LicenseClientOptions

KiwicodesLicenseClient Public Methods

LicenseResponse

GetSubscriptionsFilter

Optional filter object passed to GetSubscriptionsAsync. All properties are optional — when none are set, the endpoint returns all subscriptions for the authenticated product.

GetSubscriptionsResponse

Paginated response returned by GetSubscriptionsAsync.

GetSubscriptionResponse

Individual subscription record. Returned as items within GetSubscriptionsResponse.Subscriptions.

ConsumeFeatureResponse

Returned by ConsumeFeatureAsync after consuming a metered feature.

ConsumptionStatusResponse

Returned by GetConsumptionStatusAsync. Contains consumption status for one or more features.

FeatureConsumptionStatus

Individual feature consumption record within a ConsumptionStatusResponse.

KclmSubscriptionResponse

Returned by GetLMSubscriptionAsync. Contains KCLM subscription details with API usage history.

Activation Key Storage

The SDK provides a static ActivationKeyManager class for saving, reading, and deleting activation keys locally. Keys are encrypted at rest using AES-256-GCM with PBKDF2-SHA512 key derivation, and stored through a pluggable storage provider system.

ActivationKeyManager Static Methods

Method Parameters

Storage Providers

The SDK ships with three built-in storage providers. All providers store data that has already been AES-256-GCM encrypted by the ActivationKeyManager.

Custom Storage Providers

Implement the IActivationKeyStorageProvider interface to create a custom storage backend. The interface requires four methods:

public interface IActivationKeyStorageProvider
{
    void   Save(string productCode, string encryptedData);
    string? Read(string productCode);
    bool   Delete(string productCode);
    bool   Exists(string productCode);
}

The encryptedData passed to Save is already AES-256-GCM encrypted and Base64-encoded. Your provider only needs to persist and retrieve this string; it does not need to handle encryption.

Encryption Details

Quick Start

using KCLicenseManager.Sdk;

// Save an activation key (encrypted to local file system)
ActivationKeyManager.SaveActivationKey(
    activationKey: "ACT-KEY-123",
    passphrase:    "my-application-secret",
    productCode:   "Bonus Tools");

// Read it back
string? key = ActivationKeyManager.ReadActivationKey(
    passphrase:  "my-application-secret",
    productCode: "Bonus Tools");

// Check if one exists
bool exists = ActivationKeyManager.HasActivationKey("Bonus Tools");

// Delete it
bool deleted = ActivationKeyManager.DeleteActivationKey("Bonus Tools");

Using Different Storage Providers

using KCLicenseManager.Sdk;
using KCLicenseManager.Sdk.Storage;

// Windows Registry
var registry = new RegistryKeyStorageProvider();
ActivationKeyManager.SaveActivationKey("ACT-KEY-123", "secret", "Bonus Tools", registry);

// Secure storage (DPAPI on Windows, restricted file on macOS/Linux)
var secure = new SecureKeyStorageProvider();
ActivationKeyManager.SaveActivationKey("ACT-KEY-123", "secret", "Bonus Tools", secure);

// File system with custom path
var custom = new FileSystemKeyStorageProvider(@"C:\MyApp\Licenses");
ActivationKeyManager.SaveActivationKey("ACT-KEY-123", "secret", "Bonus Tools", custom);

Typical Integration Pattern

using KCLicenseManager.Sdk;
using KCLicenseManager.Sdk.Models;
using KCLicenseManager.Sdk.Storage;

// On application startup: try to load a saved activation key
var passphrase = "my-compiled-app-secret";
var productCode = "Bonus Tools";
string? savedKey = null;

try
{
    savedKey = ActivationKeyManager.ReadActivationKey(passphrase, productCode);
}
catch (System.Security.Cryptography.CryptographicException)
{
    // Stored data was tampered with or passphrase changed — prompt user to re-enter
    ActivationKeyManager.DeleteActivationKey(productCode);
}

if (savedKey is null)
{
    // Prompt user for their activation key
    savedKey = PromptUserForLicenseKey();
}

// Activate with the API
using var client = new KiwicodesLicenseClient(new LicenseClientOptions
{
    ApiKey = "kc_pub_your_public_key",
    SharedSecret = "kc_sec_your_shared_secret",
    ProductCode = productCode
});

var result = await client.ActivateAsync(savedKey, GetHardwareId());

if (result.IsActive)
{
    // Persist the key for next launch
    ActivationKeyManager.SaveActivationKey(savedKey, passphrase, productCode);

    // Use enabled features to gate functionality
    if (result.EnabledFeatures?.Contains("pro") == true)
        EnableProFeatures();
}

C# Examples

Activate, Check, Heartbeat, Deactivate

using KCLicenseManager.Sdk;
using KCLicenseManager.Sdk.Exceptions;
using KCLicenseManager.Sdk.Models;

var options = new LicenseClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("KCLM_API_KEY")!,
    SharedSecret = Environment.GetEnvironmentVariable("KCLM_SHARED_SECRET")!,
    ProductCode = "Bonus Tools"
};

using var client = new KiwicodesLicenseClient(options);

var licenseKey = "ACT-KEY-123";
var hardwareId = GetHardwareId();

try
{
    var activation = await client.ActivateAsync(
        licenseKey,
        hardwareId,
        userName: Environment.UserName,
        computerName: Environment.MachineName,
        autodeskId: "AUTODESK-USER-ID",
        customId: "MY-CUSTOM-IDENTIFIER");

    if (!activation.IsActive)
    {
        Console.WriteLine($"Activation failed: {activation.Status} - {activation.Description}");
        return;
    }

    Console.WriteLine($"Active. Seats: {activation.CurrentSeats}/{activation.MaxSeats}");
    Console.WriteLine($"Company: {activation.CompanyName}");
    Console.WriteLine($"Expiry: {activation.ExpiryDate}");

    // Check enabled features
    if (activation.EnabledFeatures is { Count: > 0 })
    {
        Console.WriteLine($"Features: {string.Join(", ", activation.EnabledFeatures)}");
    }

    // Check for app updates
    if (activation.LatestVersion is not null)
    {
        Console.WriteLine($"Latest version: {activation.LatestVersion}");
    }

    var status = await client.CheckAsync(licenseKey, hardwareId);
    Console.WriteLine($"Current status: {status.Status}");

    if (status.IsFloating)
    {
        await client.HeartbeatAsync(licenseKey, hardwareId);
    }

    // Call only when the user chooses to release or transfer the license.
    // await client.DeactivateAsync(licenseKey, hardwareId);
}
catch (LicenseApiException ex) when (ex.IsUnauthorized)
{
    Console.WriteLine("License API authentication failed. Check API key and shared secret.");
}
catch (LicenseApiException ex) when (ex.IsRateLimited)
{
    Console.WriteLine("License API rate limit exceeded. Retry later.");
}

static string GetHardwareId()
{
    // Replace with your product's stable identifier strategy.
    // Despite the name, this can be any unique value — it does not
    // need to be hardware-derived (e.g. a user account ID or UUID).
    return Environment.MachineName;
}

Query Subscriptions

// Get all subscriptions for the product (no filters)
var all = await client.GetSubscriptionsAsync();
Console.WriteLine($"Total: {all.Count} subscription(s)");

// Filter by email
var byEmail = await client.GetSubscriptionsAsync(new GetSubscriptionsFilter
{
    Email = "admin@example.com"
});

foreach (var sub in byEmail.Subscriptions)
{
    Console.WriteLine($"  {sub.ActKey}: {sub.CompanyName} (expires {sub.SubExpiryDate:d})");
}

// Look up specific activation keys
var byKeys = await client.GetSubscriptionsAsync(new GetSubscriptionsFilter
{
    ActivationKeys = new List<string> { "ACT-KEY-001", "ACT-KEY-002" }
});

// Filter by expiry date range
var expiringSoon = await client.GetSubscriptionsAsync(new GetSubscriptionsFilter
{
    ExpiryDateFrom = DateTime.UtcNow,
    ExpiryDateTo = DateTime.UtcNow.AddDays(30),
    PageSize = 50
});

// Paginate through all results
var filter = new GetSubscriptionsFilter { PageSize = 100 };
do
{
    var page = await client.GetSubscriptionsAsync(filter);
    foreach (var sub in page.Subscriptions)
    {
        Console.WriteLine($"{sub.ActKey}: {sub.CompanyName}");
    }
    filter.ContinuationToken = page.ContinuationToken;
} while (filter.ContinuationToken != null);

Get KCLM Subscription Info

// Retrieve KCLM subscription details with API call history and usage chart.
// The actKey must start with "KCLM".
var kclmInfo = await client.GetLMSubscriptionAsync("KCLM-YOUR-KEY");

Console.WriteLine($"Company: {kclmInfo.Subscription.CompanyName}");
Console.WriteLine($"Tier: {kclmInfo.Subscription.Tier}");
Console.WriteLine($"Expiry: {kclmInfo.Subscription.ExpiryDate}");
Console.WriteLine($"Sub Limit: {kclmInfo.Subscription.SubscriptionLimit}");

foreach (var point in kclmInfo.ApiCallHistory)
{
    Console.WriteLine($"  {point.Month}: {point.ApiCalls} calls, {point.ActiveSubscriptions} active subs");
}

// Display or save the usage chart image
if (!string.IsNullOrEmpty(kclmInfo.ChartImageBase64))
{
    byte[] chartBytes = Convert.FromBase64String(kclmInfo.ChartImageBase64);
    File.WriteAllBytes("usage-chart.png", chartBytes);
}

Bulk Create Subscriptions

using KCLicenseManager.Sdk.Models;

var response = await client.CreateSubscriptionsAsync(new List<CreateSubscriptionItem>
{
    new()
    {
        ProductName = "Bonus Tools",
        ActKey = "ACT-KEY-001",
        CompanyName = "Example Architecture Ltd",
        Email = "admin@example.com",
        FullName = "Jane Smith",
        NumberOfLicenses = 5,
        SubExpiryDate = DateTime.UtcNow.AddYears(1),
        IsFloating = false,
        UserData1 = "Customer reference",
        UserData2 = "Sales order",
        UseNamedUsers = false
    }
});

Console.WriteLine($"{response.Count} subscriptions created.");

Update Subscription

using KCLicenseManager.Sdk.Models;

var updateResponse = await client.UpdateSubscriptionAsync(new UpdateSubscriptionItem
{
    ProductName = "Bonus Tools",
    ActKey = "ACT-KEY-001",
    CompanyName = "Updated Company Name",
    Email = "newemail@example.com",
    NumberOfLicenses = 10,
    SubExpiryDate = DateTime.UtcNow.AddYears(2),
    UseNamedUsers = true
});

Console.WriteLine(updateResponse.Message);

Consume a Feature

// Consume one unit of a metered feature
var consumeResult = await client.ConsumeFeatureAsync("ACT-KEY-123", "render-credits");

if (consumeResult.IsSuccess)
{
    Console.WriteLine($"Consumed! {consumeResult.CurrentCount}/{consumeResult.MaxConsumptions} used.");
    Console.WriteLine($"Remaining: {consumeResult.Remaining}");
}
else if (consumeResult.IsLimitExceeded)
{
    Console.WriteLine($"Limit reached. Remaining: {consumeResult.Remaining}");
}

// Consume multiple units at once
var bulkConsume = await client.ConsumeFeatureAsync("ACT-KEY-123", "render-credits", quantity: 5);

Query Consumption Status

// Get status for a specific feature
var status = await client.GetConsumptionStatusAsync("ACT-KEY-123", "render-credits");

if (status.IsSuccess)
{
    foreach (var feature in status.Features)
    {
        Console.WriteLine($"{feature.FeatureName}: {feature.CurrentCount}/{feature.MaxConsumptions}");
        Console.WriteLine($"  Remaining: {feature.Remaining}, Resets: {feature.ResetPeriod}");
    }
}

// Get status for all consumable features on the subscription
var allStatus = await client.GetConsumptionStatusAsync("ACT-KEY-123");

foreach (var feature in allStatus.Features)
{
    Console.WriteLine($"{feature.FeatureCode}: {feature.CurrentCount}/{feature.MaxConsumptions}" +
        $" (Overage: {feature.IsOverage})");
}

IHttpClientFactory Integration

using KCLicenseManager.Sdk;
using KCLicenseManager.Sdk.Auth;
using KCLicenseManager.Sdk.Models;

builder.Services.AddTransient(_ => new HmacMessageHandler(apiKey, sharedSecret, productCode));

builder.Services.AddHttpClient("KiwicodesLicenseApi", client =>
{
    client.BaseAddress = new Uri("https://licenseviewer.kiwicodes.com/api/");
    client.Timeout = TimeSpan.FromSeconds(30);
})
.AddHttpMessageHandler<HmacMessageHandler>();

builder.Services.AddSingleton(sp =>
{
    var httpClient = sp.GetRequiredService<IHttpClientFactory>()
        .CreateClient("KiwicodesLicenseApi");

    return new KiwicodesLicenseClient(httpClient, new LicenseClientOptions
    {
        ApiKey = apiKey,
        SharedSecret = sharedSecret,
        ProductCode = "Bonus Tools"
    });
});

Python Examples

Reusable Signed Request Helper

import base64
import hashlib
import hmac
from datetime import datetime, timezone
from email.utils import format_datetime

import requests

API_KEY = "kc_pub_your_public_key"
SHARED_SECRET = "kc_sec_your_shared_secret"
PRODUCT_CODE = "Bonus Tools"
BASE_URL = "https://licenseviewer.kiwicodes.com/api"


def auth_headers():
    date_header = format_datetime(datetime.now(timezone.utc), usegmt=True)
    signing_string = f"kiwicodes-license\ndate: {date_header}"
    signature = base64.b64encode(
        hmac.new(
            SHARED_SECRET.encode("utf-8"),
            signing_string.encode("utf-8"),
            hashlib.sha256,
        ).digest()
    ).decode("utf-8")

    return {
        "Date": date_header,
        "Authorization": (
            f'algorithm="hmac-sha256",headers="date",'
            f'signature="{signature}",apikey="{API_KEY}",'
            f'productcode="{PRODUCT_CODE}"'
        ),
        "Content-Type": "application/json",
    }


def activate_license():
    payload = {
        "licenseKey": "ACT-KEY-123",
        "productCode": "Bonus Tools",
        "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
        "userName": "Jane Smith",
        "computerName": "WORKSTATION-01",
        "autodeskId": "AUTODESK-USER-ID",
        "customId": "MY-CUSTOM-IDENTIFIER",
    }

    response = requests.post(
        f"{BASE_URL}/v2/license/activate",
        headers=auth_headers(),
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    data = response.json()

    if data.get("statusCode") == 200:
        print(f"Active! Seats: {data['currentSeats']}/{data['maxSeats']}")

        # Check enabled features
        features = data.get("enabledFeatures", [])
        if features:
            print(f"Features: {', '.join(features)}")

        # Check for updates
        latest = data.get("latestVersion")
        if latest:
            print(f"Latest version: {latest}")

    return data


print(activate_license())

Check and Deactivate

params = {
    "licenseKey": "ACT-KEY-123",
    "productCode": "Bonus Tools",
    "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
}

check_response = requests.get(
    f"{BASE_URL}/v2/license/check",
    headers=auth_headers(),
    params=params,
    timeout=30,
)
print(check_response.json())

deactivate_response = requests.post(
    f"{BASE_URL}/v2/license/deactivate",
    headers=auth_headers(),
    json={
        "licenseKey": "ACT-KEY-123",
        "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
    },
    timeout=30,
)
print(deactivate_response.json())

Query Subscriptions

# Get all subscriptions (no filters)
all_response = requests.get(
    f"{BASE_URL}/v2/subscriptions",
    headers=auth_headers(),
    timeout=30,
)
data = all_response.json()
print(f"Found {data['count']} subscription(s)")

# Filter by email and expiry date range
params = {
    "email": "admin@example.com",
    "expiryDateFrom": "2025-01-01",
    "expiryDateTo": "2026-12-31",
    "pageSize": 50,
}
filtered = requests.get(
    f"{BASE_URL}/v2/subscriptions",
    headers=auth_headers(),
    params=params,
    timeout=30,
)
for sub in filtered.json()["subscriptions"]:
    print(f"  {sub['actKey']}: {sub['companyName']}, Licenses: {sub['numberOfLicenses']}")

# Look up specific activation keys
keys_response = requests.get(
    f"{BASE_URL}/v2/subscriptions",
    headers=auth_headers(),
    params={"activationKeys": "ACT-KEY-001,ACT-KEY-002"},
    timeout=30,
)
print(keys_response.json())

Update Subscription

update_response = requests.put(
    f"{BASE_URL}/v2/subscriptions/update",
    headers=auth_headers(),
    json={
        "productName": "Bonus Tools",
        "actKey": "ACT-KEY-001",
        "companyName": "Updated Company Name",
        "email": "newemail@example.com",
        "numberOfLicenses": 10,
        "subExpiryDate": "2028-05-06T00:00:00Z",
        "useNamedUsers": True,
    },
    timeout=30,
)
print(update_response.json())

Consume a Feature

consume_response = requests.post(
    f"{BASE_URL}/v2/consumption/consume",
    headers=auth_headers(),
    json={
        "licenseKey": "ACT-KEY-123",
        "featureCode": "render-credits",
        "quantity": 1,
    },
    timeout=30,
)
data = consume_response.json()
if data.get("statusCode") == 200:
    print(f"Consumed! {data['currentCount']}/{data['maxConsumptions']}, remaining: {data['remaining']}")
elif data.get("statusCode") == 409:
    print(f"Limit exceeded. Remaining: {data['remaining']}")

Query Consumption Status

# Status for a specific feature
status_response = requests.post(
    f"{BASE_URL}/v2/consumption/status",
    headers=auth_headers(),
    json={"licenseKey": "ACT-KEY-123", "featureCode": "render-credits"},
    timeout=30,
)
for f in status_response.json().get("features", []):
    print(f"  {f['featureName']}: {f['currentCount']}/{f['maxConsumptions']}")

# Status for all consumable features (omit featureCode)
all_status = requests.post(
    f"{BASE_URL}/v2/consumption/status",
    headers=auth_headers(),
    json={"licenseKey": "ACT-KEY-123"},
    timeout=30,
)
for f in all_status.json().get("features", []):
    print(f"  {f['featureCode']}: {f['currentCount']}/{f['maxConsumptions']} (resets: {f['resetPeriod']})")

Node.js Examples

Reusable Signed Request Helper

import crypto from "node:crypto";

const API_KEY = "kc_pub_your_public_key";
const SHARED_SECRET = "kc_sec_your_shared_secret";
const PRODUCT_CODE = "Bonus Tools";
const BASE_URL = "https://licenseviewer.kiwicodes.com/api";

function authHeaders() {
  // RFC 7231 date format
  const dateHeader = new Date().toUTCString();

  const signingString = `kiwicodes-license\ndate: ${dateHeader}`;
  const signature = crypto
    .createHmac("sha256", SHARED_SECRET)
    .update(signingString)
    .digest("base64");

  return {
    Date: dateHeader,
    Authorization:
      `algorithm="hmac-sha256",headers="date",` +
      `signature="${signature}",apikey="${API_KEY}",` +
      `productcode="${PRODUCT_CODE}"`,
    "Content-Type": "application/json",
  };
}

Activate

async function activateLicense() {
  const response = await fetch(`${BASE_URL}/v2/license/activate`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify({
      licenseKey: "ACT-KEY-123",
      productCode: "Bonus Tools",
      hardwareId: "MACHINE-GUID-OR-STABLE-ID",
      userName: "Jane Smith",
      computerName: "WORKSTATION-01",
      autodeskId: "AUTODESK-USER-ID",
      customId: "MY-CUSTOM-IDENTIFIER",
    }),
  });

  if (!response.ok && response.status !== 409) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();

  if (data.statusCode === 200) {
    console.log(`Active! Seats: ${data.currentSeats}/${data.maxSeats}`);

    // Check enabled features
    if (data.enabledFeatures?.length) {
      console.log(`Features: ${data.enabledFeatures.join(", ")}`);
    }

    // Check for updates
    if (data.latestVersion) {
      console.log(`Latest version: ${data.latestVersion}`);
    }
  } else {
    console.log(`${data.status}: ${data.description}`);
  }

  return data;
}

activateLicense().catch(console.error);

Check and Deactivate

async function checkLicense() {
  const params = new URLSearchParams({
    licenseKey: "ACT-KEY-123",
    productCode: "Bonus Tools",
    hardwareId: "MACHINE-GUID-OR-STABLE-ID",
  });

  const response = await fetch(
    `${BASE_URL}/v2/license/check?${params}`,
    { headers: authHeaders() }
  );

  return response.json();
}

async function deactivateLicense() {
  const response = await fetch(`${BASE_URL}/v2/license/deactivate`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify({
      licenseKey: "ACT-KEY-123",
      hardwareId: "MACHINE-GUID-OR-STABLE-ID",
    }),
  });

  return response.json();
}

Heartbeat

async function heartbeat() {
  const response = await fetch(`${BASE_URL}/v2/license/heartbeat`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify({
      licenseKey: "ACT-KEY-123",
      hardwareId: "MACHINE-GUID-OR-STABLE-ID",
    }),
  });

  return response.json();
}

Query Subscriptions

async function getSubscriptions(filters = {}) {
  const params = new URLSearchParams();
  for (const [key, value] of Object.entries(filters)) {
    if (value !== undefined && value !== null) {
      params.append(key, String(value));
    }
  }
  const qs = params.toString();
  const url = qs
    ? `${BASE_URL}/v2/subscriptions?${qs}`
    : `${BASE_URL}/v2/subscriptions`;

  const response = await fetch(url, { headers: authHeaders() });

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

  const data = await response.json();
  console.log(`Found ${data.count} subscription(s)`);
  for (const sub of data.subscriptions) {
    console.log(`  ${sub.actKey}: ${sub.companyName} (${sub.numberOfLicenses} seats)`);
  }

  if (data.continuationToken) {
    console.log("More results available — pass continuationToken for next page.");
  }
  return data;
}

// Examples:
// All subscriptions
getSubscriptions();

// Filter by email
getSubscriptions({ email: "admin@example.com" });

// Filter by activation keys
getSubscriptions({ activationKeys: "ACT-KEY-001,ACT-KEY-002" });

// Filter by expiry date range with pagination
getSubscriptions({ expiryDateFrom: "2025-01-01", expiryDateTo: "2026-12-31", pageSize: 50 });

Bulk Create Subscriptions

async function createSubscriptions() {
  const response = await fetch(`${BASE_URL}/v2/subscriptions/create`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify([
      {
        productName: "Bonus Tools",
        actKey: "ACT-KEY-001",
        companyName: "Example Architecture Ltd",
        email: "admin@example.com",
        fullName: "Jane Smith",
        numberOfLicenses: 5,
        subExpiryDate: "2027-05-06T00:00:00Z",
        isFloating: false,
        userData1: "Customer reference",
        userData2: "Sales order",
        useNamedUsers: false,
      },
    ]),
  });

  const result = await response.json();
  console.log(`${result.count} subscriptions created.`);
  return result;
}

Update Subscription

async function updateSubscription() {
  const response = await fetch(`${BASE_URL}/v2/subscriptions/update`, {
    method: "PUT",
    headers: authHeaders(),
    body: JSON.stringify({
      productName: "Bonus Tools",
      actKey: "ACT-KEY-001",
      companyName: "Updated Company Name",
      email: "newemail@example.com",
      numberOfLicenses: 10,
      subExpiryDate: "2028-05-06T00:00:00Z",
      useNamedUsers: true,
    }),
  });

  return response.json();
}

Consume a Feature

async function consumeFeature() {
  const response = await fetch(`${BASE_URL}/v2/consumption/consume`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify({
      licenseKey: "ACT-KEY-123",
      featureCode: "render-credits",
      quantity: 1,
    }),
  });

  const data = await response.json();
  if (data.statusCode === 200) {
    console.log(`Consumed! ${data.currentCount}/${data.maxConsumptions}, remaining: ${data.remaining}`);
  } else if (data.statusCode === 409) {
    console.log(`Limit exceeded. Remaining: ${data.remaining}`);
  }
  return data;
}

Query Consumption Status

async function getConsumptionStatus(featureCode) {
  const body = { licenseKey: "ACT-KEY-123" };
  if (featureCode) body.featureCode = featureCode;

  const response = await fetch(`${BASE_URL}/v2/consumption/status`, {
    method: "POST",
    headers: authHeaders(),
    body: JSON.stringify(body),
  });

  const data = await response.json();
  for (const f of data.features) {
    console.log(`  ${f.featureCode}: ${f.currentCount}/${f.maxConsumptions} (resets: ${f.resetPeriod})`);
  }
  return data;
}

// Single feature
getConsumptionStatus("render-credits");

// All consumable features
getConsumptionStatus();

curl Examples

Generate Headers with OpenSSL

API_KEY="kc_pub_your_public_key"
SHARED_SECRET="kc_sec_your_shared_secret"
PRODUCT_CODE="Bonus Tools"
BASE_URL="https://licenseviewer.kiwicodes.com/api"

DATE_HEADER="$(date -u +"%a, %d %b %Y %H:%M:%S GMT")"
SIGNING_STRING="kiwicodes-license
date: ${DATE_HEADER}"
SIGNATURE="$(printf '%s' "$SIGNING_STRING" | openssl dgst -sha256 -hmac "$SHARED_SECRET" -binary | base64)"
AUTH_HEADER="algorithm=\"hmac-sha256\",headers=\"date\",signature=\"${SIGNATURE}\",apikey=\"${API_KEY}\",productcode=\"${PRODUCT_CODE}\""

Activate

curl -X POST "${BASE_URL}/v2/license/activate" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123",
    "productCode": "Bonus Tools",
    "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
    "userName": "Jane Smith",
    "computerName": "WORKSTATION-01",
    "autodeskId": "AUTODESK-USER-ID",
    "customId": "MY-CUSTOM-IDENTIFIER"
  }'

Check

curl -X GET "${BASE_URL}/v2/license/check?licenseKey=ACT-KEY-123&productCode=Bonus%20Tools&hardwareId=MACHINE-GUID-OR-STABLE-ID" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}"

Deactivate

curl -X POST "${BASE_URL}/v2/license/deactivate" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123",
    "hardwareId": "MACHINE-GUID-OR-STABLE-ID"
  }'

Heartbeat

curl -X POST "${BASE_URL}/v2/license/heartbeat" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123",
    "hardwareId": "MACHINE-GUID-OR-STABLE-ID"
  }'

Query Subscriptions

# All subscriptions for the product
curl -X GET "${BASE_URL}/v2/subscriptions" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}"

# Filter by email
curl -X GET "${BASE_URL}/v2/subscriptions?email=admin%40example.com" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}"

# Filter by activation keys
curl -X GET "${BASE_URL}/v2/subscriptions?activationKeys=ACT-KEY-001,ACT-KEY-002" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}"

# Filter by expiry date range with pagination
curl -X GET "${BASE_URL}/v2/subscriptions?expiryDateFrom=2025-01-01&expiryDateTo=2026-12-31&pageSize=50" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}"

Update Subscription

curl -X PUT "${BASE_URL}/v2/subscriptions/update" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "productName": "Bonus Tools",
    "actKey": "ACT-KEY-001",
    "companyName": "Updated Company Name",
    "email": "newemail@example.com",
    "numberOfLicenses": 10,
    "subExpiryDate": "2028-05-06T00:00:00Z",
    "useNamedUsers": true
  }'

Consume a Feature

curl -X POST "${BASE_URL}/v2/consumption/consume" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123",
    "featureCode": "render-credits",
    "quantity": 1
  }'

Query Consumption Status

# Status for a specific feature
curl -X POST "${BASE_URL}/v2/consumption/status" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123",
    "featureCode": "render-credits"
  }'

# Status for all consumable features
curl -X POST "${BASE_URL}/v2/consumption/status" \
  -H "Content-Type: application/json" \
  -H "Date: ${DATE_HEADER}" \
  -H "Authorization: ${AUTH_HEADER}" \
  -d '{
    "licenseKey": "ACT-KEY-123"
  }'

API Reference

These endpoints are the HMAC-protected V2 endpoints used by the SDK and direct client integrations. Paths below are relative to the API root, for example https://licenseviewer.kiwicodes.com/api/v2/license/activate.

{
  "licenseKey": "ACT-KEY-123",
  "productCode": "Bonus Tools",
  "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
  "userName": "Jane Smith",
  "computerName": "WORKSTATION-01",
  "autodeskId": "AUTODESK-USER-ID",
  "customId": "MY-CUSTOM-IDENTIFIER"
}

{
  "status": "Active",
  "statusCode": 200,
  "description": "User added and activated successfully.",
  "licenseKey": "ACT-KEY-123",
  "productCode": "Bonus Tools",
  "hardwareId": "MACHINE-GUID-OR-STABLE-ID",
  "userName": "Jane Smith",
  "computerName": "WORKSTATION-01",
  "autodeskId": "AUTODESK-USER-ID",
  "customId": "MY-CUSTOM-IDENTIFIER",
  "expiryDate": "2027-05-06T00:00:00Z",
  "currentSeats": 1,
  "maxSeats": 5,
  "isFloating": false,
  "lastActivated": "2026-05-20T10:30:00Z",
  "companyName": "Example Architecture Ltd",
  "email": "admin@example.com",
  "fullName": "Jane Smith",
  "userData1": "Customer reference",
  "userData2": "Sales order",
  "enabledFeatures": ["pro", "lte"],
  "latestVersion": "2.1.0"
}

/v2/license/check?licenseKey=ACT-KEY-123&productCode=Bonus%20Tools&hardwareId=MACHINE-GUID-OR-STABLE-ID

{
  "licenseKey": "ACT-KEY-123",
  "hardwareId": "MACHINE-GUID-OR-STABLE-ID"
}

{
  "licenseKey": "ACT-KEY-123",
  "hardwareId": "MACHINE-GUID-OR-STABLE-ID"
}

/v2/subscriptions?email=admin%40example.com&pageSize=50

{
  "subscriptions": [
    {
      "productName": "Bonus Tools",
      "actKey": "ACT-KEY-123",
      "companyName": "Example Architecture Ltd",
      "fullName": "Jane Smith",
      "email": "admin@example.com",
      "orderDate": "2025-01-15T00:00:00Z",
      "subExpiryDate": "2027-05-06T00:00:00Z",
      "lastAccessedDate": "2026-05-20T10:30:00Z",
      "numberOfLicenses": 5,
      "disabled": false,
      "isFloating": false,
      "userData1": "Customer reference",
      "userData2": "Sales order",
      "enabledFeatures": ["pro", "lte"],
      "useNamedUsers": false
    }
  ],
  "count": 1,
  "continuationToken": null
}

/v2/public/kclm/subscription?actKey=KCLM-YOUR-KEY

[
  {
    "productName": "Bonus Tools",
    "actKey": "ACT-KEY-001",
    "companyName": "Example Architecture Ltd",
    "email": "admin@example.com",
    "fullName": "Jane Smith",
    "numberOfLicenses": 5,
    "subExpiryDate": "2027-05-06T00:00:00Z",
    "isFloating": false,
    "userData1": "Customer reference",
    "userData2": "Sales order",
    "useNamedUsers": false
  }
]

{
  "productName": "Bonus Tools",
  "actKey": "ACT-KEY-001",
  "companyName": "Updated Company Name",
  "email": "newemail@example.com",
  "numberOfLicenses": 10,
  "subExpiryDate": "2028-05-06T00:00:00Z",
  "useNamedUsers": true
}

{
  "licenseKey": "ACT-KEY-123",
  "featureCode": "render-credits",
  "quantity": 1
}

{
  "status": "OK",
  "statusCode": 200,
  "description": "Feature consumed successfully.",
  "featureCode": "render-credits",
  "currentCount": 42,
  "maxConsumptions": 100,
  "remaining": 58,
  "isOverage": false,
  "lastConsumedDate": "2026-05-26T14:30:00Z"
}

{
  "licenseKey": "ACT-KEY-123",
  "featureCode": "render-credits"
}

{
  "status": "OK",
  "statusCode": 200,
  "licenseKey": "ACT-KEY-123",
  "features": [
    {
      "featureCode": "render-credits",
      "featureName": "Render Credits",
      "currentCount": 42,
      "maxConsumptions": 100,
      "remaining": 58,
      "allowOverages": false,
      "maxOverages": 0,
      "isOverage": false,
      "resetPeriod": "Monthly",
      "lastConsumedDate": "2026-05-26T14:30:00Z",
      "lastResetDate": "2026-05-01T00:00:00Z"
    }
  ]
}

Errors and Status Values

HTTP Status Codes

LicenseResponse Status Values

ErrorResponse Shape

{
  "error": "Missing Date header.",
  "code": 401,
  "details": null
}

Rate Limits

When rate-limited, the API returns Retry-After: 3600, X-RateLimit-Limit, and X-RateLimit-Remaining: 0.

Security Notes

Protecting Secrets

• Never send the shared secret to the API. Only the signature, public API key, and product code are sent.
• Do not hard-code production secrets into public repositories, sample projects, client-side JavaScript, or logs.
• Rotate keys when a shared secret may have been exposed. Rotation invalidates existing clients using the old key pair.

Hardware ID Guidance

Despite the name, the hardwareId field does not need to contain a hardware-derived value. It can be any string that uniquely identifies the seat — for example a machine GUID, a user account ID, a database row key, or an application-generated UUID. The only requirement is that the value is unique per seat and stable (i.e. it survives reboots and normal updates). Avoid IP addresses and other values that change frequently.

If you do want to use a hardware identifier, common options by platform are listed below:

Recommended Client Behavior

• Activate on first run or when the user enters a license key.
• Use CheckAsync at startup or periodically for read-only validation.
• Use HeartbeatAsync for floating licenses while the application is running.
• Call DeactivateAsync when a user explicitly releases or transfers the seat.
• Use GetSubscriptionsAsync to query subscription details with optional filters. Pass no filter to retrieve all subscriptions for the product.
• Check EnabledFeatures in the activation response to gate product functionality.
• Check LatestVersion in the activation response to prompt users about available updates.
• Use ConsumeFeatureAsync to track metered feature usage and check IsLimitExceeded before granting access.
• Use GetConsumptionStatusAsync to display remaining quotas to users and handle overage scenarios.
• Handle business statuses gracefully; not every license failure is an exception.