Skip to content

Referenz

HTTP-API-Referenz

Eine lesbare Übersicht der HTTP-API des Issuing-Service, nach Bereichen gruppiert — Runtime, Admin, Platform, Auth, Plans, Webhooks — mit Methode, Pfad und der jeweiligen Authentifizierung.

Eine lesbare Übersicht der HTTP-API des Issuing-Service, nach Bereichen gruppiert. Diese Seite hilft Ihnen, den richtigen Endpunkt zu finden und zu wissen, wie er authentifiziert wird; die maschinenlesbare OpenAPI-Spezifikation wird mit dem Service ausgeliefert und enthält die vollständigen Request-/Response-Schemata, Feldtypen und Beispiele.

$BASE ist die URL Ihres Issuing-Service (z. B. https://keyright.delta1labs.com).

Authentifizierung auf einen Blick

Jeder Nicht-Runtime-Endpunkt ist durch eine der folgenden Methoden geschützt. Sämtliche Admin-/Plattform-Authentifizierung verwendet den Header X-Admin-Token (ein Sitzungstoken aus der Dashboard-Anmeldung wird auf dieselbe Weise übergeben).

AuthHeaderWer
keine—Runtime-Aufrufe von Endkunden (Aktivierung, Validierung, Testversion)
Mandanten-TokenX-Admin-Token: <team/session/env-admin token>ein Anbieter, der seinen eigenen Mandanten verwaltet
Plattform-TokenX-Admin-Token: <KEYRIGHT_PLATFORM_TOKEN> (+ X-Tenant für /admin/*)der Plattformbetreiber
SitzungX-Admin-Token: <session token from /auth/*>ein angemeldeter Dashboard-Benutzer
HMACX-Keyright-SignatureWebhooks von Zahlungsanbietern
Cron-SecretX-Cron-Secretder externe Benachrichtigungs-Scheduler

Die Rollen hinter einem Mandanten-Token sind nach Berechtigungen abgestuft (owner ⊃ admin ⊃ support/billing ⊃ viewer); die Mindestrolle eines Endpunkts ist unten vermerkt, wo es darauf ankommt. Das Rollenmodell finden Sie unter Admin-Dashboard.

Runtime (/v1/*) — keine Authentifizierung, aufgerufen von Ihrer App / Ihrem Kunden

MethodePfadZweck
POST/v1/activateAktiviert einen Schlüssel auf einer Maschine → belegt einen Platz, liefert einen signierten Lease. Body: { key, machineId, product }.
POST/v1/validateValidiert/aktualisiert eine Schlüssel-Maschinen-Kombination erneut, ohne einen neuen Platz zu belegen. Body: { key, machineId, product }.
POST/v1/free-seatGibt den Platz frei, den diese Maschine auf einem Schlüssel hält. Body: { key, machineId, product }.
POST/v1/trialSelf-Service-Testversion: erzeugt einen Testschlüssel für ein Produkt und sendet ihn per E-Mail (idempotent pro E-Mail-Adresse — eine erneute Anfrage sendet den vorhandenen Schlüssel noch einmal). Body { product, email, company }. Die JSON-Antwort bestätigt { ok, trial, emailed, expiresUtc, days, created } und enthält den Schlüssel nicht. CORS-offen. Siehe Kostenlose Self-Service-Testversionen.
POST/v1/coverageDeckt diese Lizenz einen bestimmten Build ab? Liefert die Berechtigung + status (Covered / NotCovered / NotConfigured) + newestCovered. Body { key, product, version, on, channel }. Der signierte Abdeckungsblock wird normalerweise mit activate/validate mitgeliefert; dies ist die explizite Prüfung. Siehe Release-Abdeckung.

Admin (/admin/*) — Mandanten-Token

Verwaltet die Produkte, Lizenzen und das Team eines Mandanten. Mit dem Plattform-Token erfordern diese Endpunkte einen X-Tenant-Header, der den Zielmandanten benennt.

Produkte & Tiers

MethodePfadZweck
GET/admin/productsListet Produkte (mit Tiers, Lizenzanzahl, Testversions-Einstellungen).
POST/admin/productsErstellt/aktualisiert ein Produkt (Name, Slug, optional trialDays/trialTier/trialSeats).
POST/admin/products/{slug}/trialAktiviert/deaktiviert die Self-Service-Testversion eines Produkts. Body { days, tier, seats } (days <= 0 deaktiviert); die Antwort gibt die Werte als { trialDays, trialTier, trialSeats } zurück.
POST/admin/products/{slug}/tiersErstellt/aktualisiert ein produktspezifisches Tier (Plätze + Entitlement-Vorlage).
POST/admin/products/{slug}/signing-keyErzeugt den produkteigenen Signaturschlüssel (oder rotiert ihn mit {"rotate":true}) → liefert signingPublicKey zum Einbetten in Ihre App.
GET/admin/tiersListet mandantenweite Tier-Vorlagen.
POST/admin/tiersErstellt/aktualisiert eine mandantenweite Tier-Vorlage.

Lizenzen

MethodePfadZweck
POST/admin/licensesStellt eine Lizenz aus (erzeugt automatisch einen Schlüssel, sofern Sie kein id übergeben).
GET/admin/licenses[?product=]Listet/filtert Lizenzen.
POST/admin/licenses/{id}/revokeWiderruft eine Lizenz (wird bei der nächsten Online-Prüfung wirksam).
POST/admin/licenses/{id}/renewVerlängert das Ablaufdatum / ändert die Plätze, ohne neuen Schlüssel.
POST/admin/licenses/{id}/transferÜberträgt die Inhaberschaft an einen neuen Lizenznehmer (auditierte Historie).
GET/admin/licenses/{id}/transfersDie Inhaberkette der Lizenz.
POST/admin/licenses/{id}/deactivateGibt den Platz einer bestimmten Maschine frei.
POST/admin/licenses/{id}/offline-leaseSigniert einen Offline-Lease für die Maschinen-ID einer netzwerkisolierten (air-gapped) Maschine.
GET/admin/licenses/{id}/activationsMaschinen, auf denen eine Lizenz aktiv ist (Gerätemetadaten + Geodaten).
POST/admin/licenses/bulk-revokeWiderruft viele Lizenzen per ID, mit Ergebnis pro Eintrag.
POST/admin/licenses/bulk-seatsÄndert Platzanzahlen gesammelt, mit Ergebnis pro Eintrag.
GET/admin/revocation-listErstellt + signiert eine verteilbare Offline-Widerrufsliste.

Release-Abdeckung — welche Versionen eine Lizenz abdeckt. Den vollständigen Leitfaden, die Feldstrukturen und die SDK-Seite finden Sie unter Release-Abdeckung.

MethodePfadZweck
GET/admin/licenses/{id}/coverageDie Abdeckung einer Lizenz: Konfiguriert-Flag, Modus, Bedingungen (Grants), Support-bis.
POST/admin/licenses/{id}/coverage/grantsHängt eine Bedingung (einen Grant) an — einen Versionsbereich und/oder ein Datumsfenster.
POST/admin/licenses/{id}/coverage/presetWendet eine Voreinstellung an (lifetime, updates-for-period, one-major, one-major + upgrade-protection, subscription, subscription-with-fallback), die zu Bedingungen expandiert wird.
POST/admin/licenses/{id}/coverage/modeSetzt den Durchsetzungsmodus: enforced oder unenforced.
POST/admin/licenses/{id}/coverage/revokeWiderruft eine Bedingung.
GET/admin/licenses/{id}/coverage/check[?version=&on=&channel=]Bewertet einen Build gegen diese Lizenz (Covered / NotCovered / NotConfigured, mit Begründung).
GET/admin/licenses/{id}/coverage/blockDer signierte Abdeckungsblock dieser Lizenz (für den Offline-/netzwerkisolierten Import).
GET/admin/products/{slug}/releasesListet die registrierten Releases eines Produkts.
POST/admin/products/{slug}/releasesRegistriert ein Release (version, Anspruchsdatum, Kanal) — Grundlage für Abdeckungsvorschauen und newest-covered.
GET/admin/products/{slug}/releases/previewAnzahl der abgedeckten / nicht abgedeckten / nicht konfigurierten Lizenzen über alle Lizenzen des Produkts.
GET/admin/products/{slug}/coverage/readinessWie viele Lizenzen noch keine Abdeckung haben — das Freigabetor vor der Durchsetzung.
POST/admin/products/{slug}/coverage/backfillGibt Bestandslizenzen eine legacy-Bedingung (lifetime, Support-Ende oder CSV-Zeilen) und ergänzt sie so nachträglich (Backfill), damit die Durchsetzung sie nie aussperrt.
POST/admin/products/{slug}/coverage/migrate[?dryRun=]Wendet eine Bedingung auf alle Lizenzen eines Produkts an; dryRun zeigt den Zugewinn vorab.
GET/admin/products/{slug}/coverage/exportExportiert den signierten Abdeckungsblock jeder Lizenz gesammelt für die netzwerkisolierte (air-gapped) Auslieferung.

Ein Kunde kann seine eigene Abdeckung im Self-Service-Portal einsehen: GET /portal/license/{id}/coverage (Magic-Link-Token des Portals) → der Statussatz in Klartext + Support-bis.

Team

MethodePfadAuthZweck
GET/POST/admin/teamownerListet Teammitglieder / lädt sie ein (die Einladung sendet ein Einmal-Token per E-Mail).
POST/admin/team/{id}ownerAktiviert/deaktiviert ein Mitglied.
POST/admin/team/{id}/set-passwordownerLegt das Dashboard-Passwort eines Mitglieds fest.

Arbeitsbereich, Berichte & Integration

MethodePfadZweck
GET/admin/overviewDashboard-Startseite: Abonnementübersicht, Zähler, Aufschlüsselung pro Produkt, Trend, anstehende Verlängerungen.
GET/admin/accountMandant + Plan + Nutzung + der Integrations-Block (Basis-URL, öffentlicher Signaturschlüssel, Webhook-URL).
GET/admin/statsSummen pro Produkt (Lizenzen, aktive Plätze, bald ablaufend, widerrufen).
GET/admin/usageZugewiesene/belegte Plätze pro Lizenz + Summen (nutzungsbasierte Abrechnung).
GET/admin/export[?product=]Vollständiges Bündel aus Lizenzen + Aktivierungen.
GET/admin/auditZuordenbares Audit-Protokoll aller ändernden Aktionen.
GET/admin/public-keyDer öffentliche Signaturschlüssel des Mandanten. null, bis ein Mandantenschlüssel existiert — für einen produktspezifischen Schlüssel verwenden Sie stattdessen POST /admin/products/{slug}/signing-key.
GET/admin/self-licenseNur Self-Hosting: der eigene Lizenzstatus dieser Instanz — status, edition, isTrial, phase (active/expiring/grace/gated), daysUntilExpiry, graceDaysLeft.
POST/admin/workspaceOwner: Name, Logo und Onboarding-Flag des Arbeitsbereichs.
POST/admin/webhook-secret/rotateOwner: rotiert das Fulfillment-Webhook-Secret dieses Mandanten.
POST/admin/billing/checkoutOwner: öffnet einen Lemon-Squeezy-Checkout zum Upgrade des Plans.
POST/GET/admin/resellers, /admin/resellers/{id}Verwaltet Reseller (begrenzte, produktbezogene Aussteller).

Platform (/platform/*) — Plattform-Token

Die mandantenfähige Betreiberoberfläche. Deaktiviert (503), wenn KEYRIGHT_PLATFORM_TOKEN nicht gesetzt ist (Single-Tenant-Self-Hosting).

MethodePfadZweck
POST/platform/tenantsErstellt ein Unternehmen/einen Mandanten → liefert das initiale Owner-Token, den öffentlichen Signaturschlüssel und das Webhook-Secret.
GET/platform/tenants[?slug=]Listet Mandanten.
POST/platform/tenants/{id}Aktivieren/deaktivieren, Plan und Abonnementstatus setzen.
POST/platform/tenants/{id}/signing-keyImportiert (PKCS#8 von Nebula) oder erzeugt einen Mandanten-Signaturschlüssel.
POST/platform/tenants/{id}/rotate-signing-keyRotiert den Signaturschlüssel eines Mandanten.
POST/platform/tenants/{id}/rotate-webhook-secretRotiert das Webhook-Secret eines Mandanten.
GET/platform/plansVollständiger Plankatalog (inkl. nicht öffentlicher Pläne).
POST/platform/plans/{key}Erstellt/aktualisiert Preise, Kontingente und Funktionen eines Plans.

Auth (/auth/*) — Dashboard-Anmeldung → Sitzungstoken

Diese Endpunkte erzeugen ein Sitzungstoken, das Sie anschließend als X-Admin-Token an die oben genannten /admin/*-Endpunkte übergeben. Die Anmeldung erfolgt pro Mandant (übergeben Sie X-Tenant; Standard ist default).

MethodePfadZweck
POST/auth/loginE-Mail + Passwort → eine MFA-Abfrage.
POST/auth/mfaE-Mail + Passwort + TOTP-Code → Sitzungstoken.
POST/auth/ssoTauscht ein validiertes OIDC-ID-Token gegen ein Sitzungstoken.
POST/auth/sessionTauscht ein Zugriffstoken einer nativen / Social-Anmeldung gegen ein Sitzungstoken.
GET/auth/oauth/{provider} → /auth/oauth/{provider}/callbackNatives Google-/GitHub-OAuth auf Ihrer eigenen Domain.

Plans (/plans) — öffentlich

MethodePfadAuthZweck
GET/planskeineÖffentlicher Preiskatalog (als öffentlich markierte Pläne), für eine Preisseite oder die Registrierung.

Webhooks (/webhooks/*) — HMAC

Fulfillment-Auslöser: Ein Zahlungsanbieter (oder ein schlanker Adapter) sendet per POST ein normalisiertes Ereignis, HMAC-signiert über den rohen Body in X-Keyright-Signature. „Paid“ erzeugt eine Lizenz (idempotent pro Bestellreferenz); „refund“/„cancel“ widerruft sie. Die Zahlungsabwicklung selbst liegt außerhalb des Umfangs.

MethodePfadZweck
POST/webhooks/fulfill/{slug}Webhook pro Mandant; der Mandant wird aus der Route entnommen und mit dessen Secret verifiziert.
POST/webhooks/fulfillVeralteter deploymentweiter Webhook (Single-Tenant, KEYRIGHT_WEBHOOK_SECRET).

Betrieb

MethodePfadAuthZweck
GET/healthkeineLiveness-/Versionsprüfung.
GET/brandingkeineWhite-Label-Markenname/Logo/Farbe für jede Oberfläche.
POST/internal/notifications/runCron-SecretFührt den täglichen Scan auf Ablauf/Platzlimit aus (von einem externen Scheduler angestoßen).
verschiedene/portal/*Magic-LinkSelf-Service-Kundenportal (Lizenzen einsehen, Schlüssel/Datei erneut herunterladen, Plätze freigeben).

Das Dashboard selbst wird unter /dashboard ausgeliefert — siehe Admin-Dashboard.