Lizenzschlüssel-API
Lizenzen für eigene Software – Schlüssel aktivieren, prüfen und abmelden, Token offline verifizieren.
Für Anwendungen mit der Funktion „Lizenzschlüssel“ (Konsole → Anwendung → Einstellungen). Du stellst Lizenzschlüssel aus, deine Software aktiviert sie auf einem Gerät und bekommt ein signiertes Token, das sie auch offline prüfen kann.
Basis-URL je Anwendung: https://updates.cyrellian.com/<anwendung>/license/v1 – steht mit dem öffentlichen
Schlüssel auf der Übersichtsseite der Anwendung in der Konsole.
| Aufruf | Body | Antwort |
|---|---|---|
POST activate |
{key, machineId, name?, version?} |
{status: "active", token, license} |
POST validate |
{key oder token, machineId, version?} |
{status: "active", token, license} |
POST deactivate |
{key oder token, machineId} |
{ok: true} |
POST trial |
{machineId, name?, version?} |
{status: "active", token, license} mit plan: "trial" (siehe „Testphase“) |
GET public-key |
– | {algorithm: "Ed25519", keys: [{publicKey, active}]} |
machineId: stabile Kennung des Geräts bzw. der Installation, 4–200 Zeichen aus Buchstaben, Ziffern und. _ : -(z. B. ein Hash aus Rechner-ID und Benutzer).activatebelegt einen Geräteplatz. Dasselbe Gerät erneut zu aktivieren zählt nicht doppelt.validateist das Lebenszeichen: einmal beim Start und etwa täglich. Es liefert ein frisches Token und merkt sofort, wenn ein Schlüssel gesperrt, widerrufen oder abgelaufen ist.deactivategibt den Platz wieder frei (Deinstallation, Umzug auf einen neuen Rechner). Kunden können Geräte auch selbst unter account.cyrellian.com abmelden.
license enthält {plan, planName, features, expiresAt, tokenExpiresAt, maxActivations, manageUrl?}.
Verwaltungscode
Pro Anwendung einschaltbar (Konsole → Anwendung bearbeiten → „Verwaltungscode zu jedem Schlüssel“). Dann bekommt
jeder neue Schlüssel zusätzlich einen Verwaltungscode (VC-XXXXX-XXXXX-XXXXX-XXXXX, nur einmal angezeigt). Der
Käufer kann den Lizenzschlüssel weitergeben und behält den Code: Unter https://account.cyrellian.com/manage sieht
er damit – ohne Konto – Status, Ablauf und alle aktivierten Geräte und meldet Geräte ab. Die API liefert diese
Adresse als license.manageUrl, damit deine Software „Lizenz verwalten“ verlinken kann. Verlorene Codes erzeugst du
in der Konsole neu (der alte wird ungültig); ältere Schlüssel bekommen dort ihren ersten Code.
Testphase
Pro Anwendung einschaltbar (Konsole → Anwendung → Einstellungen → Lizenzschlüssel): Länge in Tagen und der
Tarif, dessen Funktionen die Testphase bekommt. Deine Software startet sie ohne Schlüssel mit
POST trial {machineId, name?, version?} und bekommt ein ganz normales Token – mit plan: "trial", den Funktionen
des gewählten Tarifs und licenseExpiresAt = Ende der Testphase (exp des Tokens höchstens bis dahin).
- Einmal pro Gerät (
machineId): erneutestrialliefert die laufende Testphase wieder, nach ihrem Ende kommtexpired(403). Pro IP starten höchstens 10 neue Testphasen am Tag. validatemit dem Token verlängert es wie bei einem Schlüssel, bis die Testphase endet; danachexpired. Dann fällt deine Software auf ihre freie Stufe zurück (Daten nie sperren) und bietet den Kauf eines Schlüssels an.deactivatemit einem Testphasen-Token antwortet{ok: true}, die Testphase bleibt verbraucht.- Wird auf dem Gerät später ein Schlüssel aktiviert, zählt die Konsole die Testphase als gekauft. Dort siehst du aktive und abgelaufene Testphasen und setzt einzelne zurück – das Gerät kann dann eine neue starten.
- Ist keine Testphase eingestellt, antwortet
trialmitnot_configured(404).
const state = await license.startTrial({ name: "Laptop" }); // plan "trial"
// später: check() → {valid: false, reason: "expired"} → freie StufeFehler
HTTP 4xx mit {error: <code>}:
| Code | Bedeutung |
|---|---|
invalid_request |
Pflichtfeld fehlt oder machineId/Schlüssel hat das falsche Format |
invalid_key (404) |
Schlüssel unbekannt |
expired / suspended / revoked (403) |
Lizenz abgelaufen, gesperrt oder widerrufen |
limit_reached (403) |
Alle Geräteplätze belegt – erst ein Gerät abmelden |
not_activated (403) |
Dieses Gerät ist für den Schlüssel nicht (mehr) aktiviert |
rate_limited (429) |
Zu viele Anfragen (bzw. zu viele unbekannte Schlüssel) von dieser IP |
not_configured (503) |
Die Anwendung hat keinen Signaturschlüssel |
not_configured (404) |
Nur trial: Die Anwendung bietet keine Testphase |
Token
base64url(JSON) + "." + base64url(Ed25519-Signatur über den base64url-Teil), signiert mit dem Schlüssel der
Anwendung:
{
"v": 1,
"typ": "license_key",
"iss": "https://updates.cyrellian.com/mein-tool/license/v1",
"app": "mein-tool",
"sub": "<machineId>",
"kid": "<Schlüssel-ID>",
"plan": "pro",
"planName": "Pro",
"features": { "pro": true, "maxProjects": null },
"status": "active",
"licenseExpiresAt": "2027-10-03T23:59:59.000Z",
"addons": ["brother-pr"],
"iat": 1790000000,
"exp": 1790604800
}Prüfe offline: Signatur mit dem öffentlichen Schlüssel (Base64, SPKI DER), sub = eigene machineId, exp in
der Zukunft. addons gibt es nur bei Anwendungen mit Add-ons: die freigeschalteten Bezahl-Add-ons dieses Schlüssels
(siehe Update-API); license.addons in der Antwort enthält dasselbe. Ein Token gilt 7 Tage (höchstens bis zum Ende der Lizenz) – so funktioniert deine Software ohne
Internet weiter, und eine Sperre wirkt spätestens nach dieser Zeit.
Mit dem Client-Paket
@cyrellian/license-client (keine Abhängigkeiten; Node 20+, Electron, Bun, Deno, Browser). Das Paket ist privat und
liegt im Cyrellian-Repository (packages/license-client) – die eine Datei src/index.ts übernimmst du in deine Software:
import { LicenseClient } from "@cyrellian/license-client";
const license = new LicenseClient({
baseUrl: "https://updates.cyrellian.com/mein-tool/license/v1",
publicKeys: ["MCowBQYDK2VwAyEA…"],
machineId,
storage: { get: () => readToken(), set: (t) => writeToken(t) },
version: "1.4.0",
});
await license.activate("ABCDE-FGHJK-LMNPQ-RSTUV-WXYZ2", { name: "Laptop" });
const state = await license.check(); // online prüfen, offline das gespeicherte Token
if (state.valid && state.features.pro) {
// Pro-Funktionen freischalten
}
await license.deactivate();Direkt per HTTP
curl -X POST https://updates.cyrellian.com/mein-tool/license/v1/activate \
-H "content-type: application/json" \
-d '{"key":"ABCDE-FGHJK-LMNPQ-RSTUV-WXYZ2","machineId":"laptop-7f3a9c","name":"Laptop"}'