Zum Inhalt springen
CCyrellian
Suchen…Ctrl K

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).
  • activate belegt einen Geräteplatz. Dasselbe Gerät erneut zu aktivieren zählt nicht doppelt.
  • validate ist 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.
  • deactivate gibt 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): erneutes trial liefert die laufende Testphase wieder, nach ihrem Ende kommt expired (403). Pro IP starten höchstens 10 neue Testphasen am Tag.
  • validate mit dem Token verlängert es wie bei einem Schlüssel, bis die Testphase endet; danach expired. Dann fällt deine Software auf ihre freie Stufe zurück (Daten nie sperren) und bietet den Kauf eines Schlüssels an. deactivate mit 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 trial mit not_configured (404).
const state = await license.startTrial({ name: "Laptop" });   // plan "trial"
// später: check() → {valid: false, reason: "expired"} → freie Stufe

Fehler

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"}'
War diese Seite hilfreich?Aktualisiert am 17. Oktober 2026