SDKs & API wrapper

Two small libraries with no heavy dependencies: one lives inside your software and checks a license; the other lives on your server and issues keys. Both are built to be safe by default, and both only ever talk to the documented public APIs.

Which library do I need?

Neither library can reach the dashboard APIs (/api/account, /api/admin). Those belong to browsers with a signed-in session and are deliberately not scriptable.

Get the files

They are single, readable source files — vendor them into your project rather than depending on a package registry, so you can review exactly what runs in your app.

Copy your product ID from the product’s page in the dashboard, and the service’s public key from the guide (or GET /api/v1/public-key). Compile the public key into your app rather than reading it from a file the user can edit.

License client

Python

from license_client import LicenseClient

client = LicenseClient(
    base_url="https://license.foliox.sbs",
    product="YOUR_PRODUCT_ID",          # from the product page in your dashboard
    public_key_b64=PUBLIC_KEY,          # from the guide page - public, not a secret
)
result = client.check(license_key)      # activates on first run, verifies afterwards
if not result.valid:
    raise SystemExit(f"Not licensed: {result.reason}")

Node.js

const { LicenseClient } = require('./licenseClient');

const client = new LicenseClient({
  baseUrl: 'https://license.foliox.sbs',
  product: 'YOUR_PRODUCT_ID',
  publicKeyB64: PUBLIC_KEY,
});
const result = await client.check(licenseKey);
if (!result.valid) throw new Error('Not licensed: ' + result.reason);

Go

client, err := licenseclient.New("https://license.foliox.sbs", "YOUR_PRODUCT_ID", publicKey)
if err != nil { log.Fatal(err) }        // unsafe or malformed configuration is reported here
result := client.Check(licenseKey)
if !result.Valid { log.Fatalf("not licensed: %s", result.Reason) }

Rust

let client = LicenseClient::new("https://license.foliox.sbs", "YOUR_PRODUCT_ID", PUBLIC_KEY)?;
let result = client.check(license_key);
if !result.valid {
    eprintln!("not licensed: {:?}", result.reason);
    std::process::exit(1);
}

The first check on a computer activates the key (binding it to that device); every later check verifies it. You never call the two endpoints yourself.

What a check returns

check() never throws for runtime conditions — a wrong key, a dead network and a tampered answer are all just a result with valid false and a reason. Only bad configuration (an http:// address, a malformed public key) is reported as an error, immediately, when the client is created.

result = client.check(license_key)
if result.valid:
    start_app()                         # result.from_offline_cache tells you it ran on the 72-hour grace
elif result.reason in ("network_error", "rate_limited"):
    show("Could not reach the license server. Check your connection and try again.")
elif result.reason == "hwid_mismatch":
    show("This key is bound to another computer. Request a device reset on the license check page.")
elif result.reason in ("expired", "revoked", "suspended", "not_found", "malformed_key"):
    show("This license is not valid: " + result.reason)
else:                                   # signature_invalid, clock_skew, invalid_response ...
    show("The license answer could not be trusted (" + result.reason + "). Check the system clock.")

Options

The defaults suit most apps. In Python they are keyword arguments, in Node.js properties of the options object, in Go With… functions passed to New, in Rust fields of ClientOptions.

Offline grace

If the server can’t be reached, the client uses the last valid signed answer for as long as the server allowed (72 hours from that answer) — and never past the key’s own expiry. The stored answer:

• is re-verified with the public key every time it is read, so editing the file only breaks it;
• is bound to this device, this product and this key (a fingerprint, never the key itself), so copying it to another computer or using it for another key does nothing;
• is deleted the moment the server gives a definite “no”, so a revoked license can’t come back to life offline;
• carries a “last seen” marker, so setting the system clock back to stretch the grace is detected (clock_rollback).

This keeps honest customers working through an outage. It is a resilience feature, not a security boundary — see what no client can do.

Helpers

Each library also exposes normalize_key and is_valid_key_format (the key’s check character is validated locally, so a typo never costs a request), compute_hwid, and clear_cache for “sign out” flows. The device ID is identical in every language, so switching libraries never un-binds a customer.

Automation client

For your server: create keys after a purchase, look one up, revoke it, or reset its device. It authenticates with an API token and needs the matching permission for each call.

Python

import os
from automation_client import AutomationClient, PlanLimitError, RateLimitedError

api = AutomationClient("https://license.foliox.sbs", token=os.environ["LICENSE_API_TOKEN"])

keys = api.create_keys("YOUR_PRODUCT_ID", count=1, duration_days=365, customer_email="[email protected]")
print(keys[0]["key"], keys[0]["status"])

info = api.get_key(keys[0]["key"])              # status, expires_at, device_bound ...
api.revoke_key(keys[0]["key"])                  # stops validating immediately
api.reset_device(keys[0]["key"])                # let the customer move to a new computer

Node.js

const { AutomationClient, PlanLimitError } = require('./automationClient');

const api = new AutomationClient({ baseUrl: 'https://license.foliox.sbs', token: process.env.LICENSE_API_TOKEN });

const [key] = await api.createKeys('YOUR_PRODUCT_ID', { count: 1, durationDays: 365, customerEmail: '[email protected]' });
console.log(key.key, key.status);

const info = await api.getKey(key.key);
await api.revokeKey(key.key);
await api.resetDevice(key.key);

Errors

Every failure is a typed error carrying the HTTP status, the server’s code and a message — never the token.

Retries, and why creating keys is different

Reads and the repeatable actions (revoke, restore, reset) are retried on network errors, 429 and 5xx. Creating keys is not repeatable — if a request times out you cannot know whether the keys were made — so it is retried only when it provably never arrived (a refused connection, a failed DNS lookup, or a 429 that was refused before processing). Make your own side idempotent, as in this webhook:

# A checkout webhook. Your own database remembers which order already got a key, so a webhook that is
# delivered twice (they always are, sooner or later) can never mint two.
@app.post("/webhooks/order-paid")
def order_paid():
    order = verify_and_parse(request)               # check the shop's signature first
    existing = db.key_for_order(order.id)
    if existing:
        return {"key": existing}
    try:
        [created] = api.create_keys("YOUR_PRODUCT_ID", customer_email=order.email, duration_days=order.days, notes=f"order {order.id}")
    except PlanLimitError:
        alert_me("License plan limit reached")     # the buyer has paid: never lose the order
        return {"queued": True}, 202
    db.save_key_for_order(order.id, created["key"])
    return {"key": created["key"]}

What the libraries protect against

What no client library can do

Someone in full control of the computer running your software can patch it to skip the check, replace the library, emulate a device ID, or freeze the clock. No license check that runs on the user’s machine can prevent that — and we would rather say so than pretend. What the service does give you: a key that only works on one device at a time, instant revocation, answers that can’t be forged, and a full audit trail. To make bypassing worth less:

• Keep value on your server. The strongest protection is that something the user needs (a download, an API, a content pack) is only served to a valid license. Then a patched client gets nothing.
• Check on start-up and periodically (every few hours is plenty), from more than one place in your code, and don’t log or display the reason details to the user in a way that maps out your logic.
• Compile the public key into your binary; obfuscate or strip your build as suits your platform.
• Watch the key’s history in the dashboard: repeated hwid_mismatch attempts usually mean a shared key — revoke it.
• Inside the freshness window a captured answer can be replayed by someone who controls the machine’s network stack; that is inherent to a protocol without a per-request challenge, which is why the window is short.

Integration checklist

• The public key and product ID are in your code; no token is.
• You treat every valid: false — including network_error with no cache — as not licensed.
• Your UI explains hwid_mismatch, expired and clock_skew in plain words.
• You re-check periodically, not only at launch, and never in a tight loop (the API is rate-limited).
• Your checkout webhook is idempotent and alerts you on PlanLimitError.
• You keep the libraries up to date and re-read this page when the version changes.

Compatibility and upgrading

The wire protocol and the signed format are unchanged, and the device ID is computed exactly as before, so upgrading the library never un-binds an existing customer. What is different in version 2:

• Plain http:// addresses (other than localhost) are refused, and product must be a valid product ID — both reported when the client is created.
• check() returns a result instead of raising, in every language (Python and Node.js used to raise on a bad signature; the result now says signature_invalid).
• The stored offline answer has a new, device-bound format. The first run after upgrading needs one online check; older cache files are ignored.
• New fields on the result (key_id, checked_at, message) and new options; existing arguments and field names are unchanged.

How the libraries are tested

Every library runs in our test suite against a real server and against deliberately misbehaving stand-ins: forged signatures, replayed and stale answers, another product’s answer, redirects, oversized and non-JSON responses, servers that hang or fail, a tampered or copied cache, a clock set back, and a certificate that can’t be verified. Each protection listed above is covered by a test.