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}");
}
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.

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"

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 and signature in the Authorization header.

.NET SDK Reference

LicenseClientOptions

KiwicodesLicenseClient Public Methods

LicenseResponse

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);

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

    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 machine identifier strategy.
    return Environment.MachineName;
}

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"
    }
});

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)
});

Console.WriteLine(updateResponse.Message);

IHttpClientFactory Integration

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

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

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"
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}"'
        ),
        "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",
    }

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


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())

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",
    },
    timeout=30,
)
print(update_response.json())

curl Examples

Generate Headers with OpenSSL

API_KEY="kc_pub_your_public_key"
SHARED_SECRET="kc_sec_your_shared_secret"
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}\""

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"
  }'

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"
  }'

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"
  }'

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"
}

/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"
}

[
  {
    "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"
  }
]

{
  "productName": "Bonus Tools",
  "actKey": "ACT-KEY-001",
  "companyName": "Updated Company Name",
  "email": "newemail@example.com",
  "numberOfLicenses": 10,
  "subExpiryDate": "2028-05-06T00: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 and public API key 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

Choose a stable value that survives reboots and normal updates. Avoid IP addresses and other values that change frequently.

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.
• Handle business statuses gracefully; not every license failure is an exception.