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).
| Auth | Header | Wer |
|---|---|---|
| keine | — | Runtime-Aufrufe von Endkunden (Aktivierung, Validierung, Testversion) |
| Mandanten-Token | X-Admin-Token: <team/session/env-admin token> | ein Anbieter, der seinen eigenen Mandanten verwaltet |
| Plattform-Token | X-Admin-Token: <KEYRIGHT_PLATFORM_TOKEN> (+ X-Tenant für /admin/*) | der Plattformbetreiber |
| Sitzung | X-Admin-Token: <session token from /auth/*> | ein angemeldeter Dashboard-Benutzer |
| HMAC | X-Keyright-Signature | Webhooks von Zahlungsanbietern |
| Cron-Secret | X-Cron-Secret | der 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
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /v1/activate | Aktiviert einen Schlüssel auf einer Maschine → belegt einen Platz, liefert einen signierten Lease. Body: { key, machineId, product }. |
| POST | /v1/validate | Validiert/aktualisiert eine Schlüssel-Maschinen-Kombination erneut, ohne einen neuen Platz zu belegen. Body: { key, machineId, product }. |
| POST | /v1/free-seat | Gibt den Platz frei, den diese Maschine auf einem Schlüssel hält. Body: { key, machineId, product }. |
| POST | /v1/trial | Self-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/coverage | Deckt 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
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /admin/products | Listet Produkte (mit Tiers, Lizenzanzahl, Testversions-Einstellungen). |
| POST | /admin/products | Erstellt/aktualisiert ein Produkt (Name, Slug, optional trialDays/trialTier/trialSeats). |
| POST | /admin/products/{slug}/trial | Aktiviert/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}/tiers | Erstellt/aktualisiert ein produktspezifisches Tier (Plätze + Entitlement-Vorlage). |
| POST | /admin/products/{slug}/signing-key | Erzeugt den produkteigenen Signaturschlüssel (oder rotiert ihn mit {"rotate":true}) → liefert signingPublicKey zum Einbetten in Ihre App. |
| GET | /admin/tiers | Listet mandantenweite Tier-Vorlagen. |
| POST | /admin/tiers | Erstellt/aktualisiert eine mandantenweite Tier-Vorlage. |
Lizenzen
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /admin/licenses | Stellt eine Lizenz aus (erzeugt automatisch einen Schlüssel, sofern Sie kein id übergeben). |
| GET | /admin/licenses[?product=] | Listet/filtert Lizenzen. |
| POST | /admin/licenses/{id}/revoke | Widerruft eine Lizenz (wird bei der nächsten Online-Prüfung wirksam). |
| POST | /admin/licenses/{id}/renew | Verlä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}/transfers | Die Inhaberkette der Lizenz. |
| POST | /admin/licenses/{id}/deactivate | Gibt den Platz einer bestimmten Maschine frei. |
| POST | /admin/licenses/{id}/offline-lease | Signiert einen Offline-Lease für die Maschinen-ID einer netzwerkisolierten (air-gapped) Maschine. |
| GET | /admin/licenses/{id}/activations | Maschinen, auf denen eine Lizenz aktiv ist (Gerätemetadaten + Geodaten). |
| POST | /admin/licenses/bulk-revoke | Widerruft viele Lizenzen per ID, mit Ergebnis pro Eintrag. |
| POST | /admin/licenses/bulk-seats | Ändert Platzanzahlen gesammelt, mit Ergebnis pro Eintrag. |
| GET | /admin/revocation-list | Erstellt + 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.
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /admin/licenses/{id}/coverage | Die Abdeckung einer Lizenz: Konfiguriert-Flag, Modus, Bedingungen (Grants), Support-bis. |
| POST | /admin/licenses/{id}/coverage/grants | Hängt eine Bedingung (einen Grant) an — einen Versionsbereich und/oder ein Datumsfenster. |
| POST | /admin/licenses/{id}/coverage/preset | Wendet 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/mode | Setzt den Durchsetzungsmodus: enforced oder unenforced. |
| POST | /admin/licenses/{id}/coverage/revoke | Widerruft 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/block | Der signierte Abdeckungsblock dieser Lizenz (für den Offline-/netzwerkisolierten Import). |
| GET | /admin/products/{slug}/releases | Listet die registrierten Releases eines Produkts. |
| POST | /admin/products/{slug}/releases | Registriert ein Release (version, Anspruchsdatum, Kanal) — Grundlage für Abdeckungsvorschauen und newest-covered. |
| GET | /admin/products/{slug}/releases/preview | Anzahl der abgedeckten / nicht abgedeckten / nicht konfigurierten Lizenzen über alle Lizenzen des Produkts. |
| GET | /admin/products/{slug}/coverage/readiness | Wie viele Lizenzen noch keine Abdeckung haben — das Freigabetor vor der Durchsetzung. |
| POST | /admin/products/{slug}/coverage/backfill | Gibt 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/export | Exportiert 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
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| GET/POST | /admin/team | owner | Listet Teammitglieder / lädt sie ein (die Einladung sendet ein Einmal-Token per E-Mail). |
| POST | /admin/team/{id} | owner | Aktiviert/deaktiviert ein Mitglied. |
| POST | /admin/team/{id}/set-password | owner | Legt das Dashboard-Passwort eines Mitglieds fest. |
Arbeitsbereich, Berichte & Integration
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /admin/overview | Dashboard-Startseite: Abonnementübersicht, Zähler, Aufschlüsselung pro Produkt, Trend, anstehende Verlängerungen. |
| GET | /admin/account | Mandant + Plan + Nutzung + der Integrations-Block (Basis-URL, öffentlicher Signaturschlüssel, Webhook-URL). |
| GET | /admin/stats | Summen pro Produkt (Lizenzen, aktive Plätze, bald ablaufend, widerrufen). |
| GET | /admin/usage | Zugewiesene/belegte Plätze pro Lizenz + Summen (nutzungsbasierte Abrechnung). |
| GET | /admin/export[?product=] | Vollständiges Bündel aus Lizenzen + Aktivierungen. |
| GET | /admin/audit | Zuordenbares Audit-Protokoll aller ändernden Aktionen. |
| GET | /admin/public-key | Der ö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-license | Nur Self-Hosting: der eigene Lizenzstatus dieser Instanz — status, edition, isTrial, phase (active/expiring/grace/gated), daysUntilExpiry, graceDaysLeft. |
| POST | /admin/workspace | Owner: Name, Logo und Onboarding-Flag des Arbeitsbereichs. |
| POST | /admin/webhook-secret/rotate | Owner: rotiert das Fulfillment-Webhook-Secret dieses Mandanten. |
| POST | /admin/billing/checkout | Owner: ö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).
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /platform/tenants | Erstellt 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-key | Importiert (PKCS#8 von Nebula) oder erzeugt einen Mandanten-Signaturschlüssel. |
| POST | /platform/tenants/{id}/rotate-signing-key | Rotiert den Signaturschlüssel eines Mandanten. |
| POST | /platform/tenants/{id}/rotate-webhook-secret | Rotiert das Webhook-Secret eines Mandanten. |
| GET | /platform/plans | Vollstä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).
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /auth/login | E-Mail + Passwort → eine MFA-Abfrage. |
| POST | /auth/mfa | E-Mail + Passwort + TOTP-Code → Sitzungstoken. |
| POST | /auth/sso | Tauscht ein validiertes OIDC-ID-Token gegen ein Sitzungstoken. |
| POST | /auth/session | Tauscht ein Zugriffstoken einer nativen / Social-Anmeldung gegen ein Sitzungstoken. |
| GET | /auth/oauth/{provider} → /auth/oauth/{provider}/callback | Natives Google-/GitHub-OAuth auf Ihrer eigenen Domain. |
Plans (/plans) — öffentlich
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| GET | /plans | keine | Ö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.
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /webhooks/fulfill/{slug} | Webhook pro Mandant; der Mandant wird aus der Route entnommen und mit dessen Secret verifiziert. |
| POST | /webhooks/fulfill | Veralteter deploymentweiter Webhook (Single-Tenant, KEYRIGHT_WEBHOOK_SECRET). |
Betrieb
| Methode | Pfad | Auth | Zweck |
|---|---|---|---|
| GET | /health | keine | Liveness-/Versionsprüfung. |
| GET | /branding | keine | White-Label-Markenname/Logo/Farbe für jede Oberfläche. |
| POST | /internal/notifications/run | Cron-Secret | Führt den täglichen Scan auf Ablauf/Platzlimit aus (von einem externen Scheduler angestoßen). |
| verschiedene | /portal/* | Magic-Link | Self-Service-Kundenportal (Lizenzen einsehen, Schlüssel/Datei erneut herunterladen, Plätze freigeben). |
Das Dashboard selbst wird unter /dashboard ausgeliefert — siehe Admin-Dashboard.