Lizenzierungs-API

Die Lizenzierungs-API ermöglicht es dir, Lizenzrichtlinien zu erstellen, Schlüssel auszustellen, diese zur Laufzeit zu validieren, Plätze und Geräte zu verwalten und die Schlüsselausstellung über Zahlungs-Webhooks zu automatisieren. Sie unterstützt Online-Validierung, Offline-JWT-Fallback und hybride Modi.

Zwei Zielgruppen, zwei Authentifizierungsebenen:

Zielgruppe	Authentifizierung	Endpunkte
Deine App / SDK (Laufzeit)	Kein Bearer-Token erforderlich	`/validate`, `/activate`, `/deactivate`, `/usage`, `/revocation-list`
Admin / Konsole (Verwaltung)	Bearer-Token + Berechtigung	Alle anderen

Alle Endpunkte erfordern den x-tenant-Header.

Richtlinien

Richtlinien definieren, was eine Lizenz gewährt — Funktionen, Plätze, Geräte, Ablauf, Schlüsselformat und Validierungsmodus.

GET/api/licensing/policiesRequires: manage:license-policies

Alle Richtlinien für den aktuellen Mandanten auflisten. Unterstützt Paginierung und Suche.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	`number`	Seitennummer (Standard: 1)
`limit`	`number`	Einträge pro Seite (Standard: 20)
`search`	`string`	Nach Name oder Slug filtern

Erfolgsantwort


{
  "success": true,
  "data": [
    {
      "id": "pol_abc123",
      "name": "Pro Plan",
      "slug": "pro-plan",
      "validationMode": "HYBRID",
      "isActive": true,
      "offlineGraceDays": 7,
      "revocationTtlMin": 60,
      "dimensions": {
        "seats": { "enabled": true, "defaultMax": 5 },
        "devices": { "enabled": true, "defaultMax": 3 },
        "expiry": { "enabled": true, "defaultDays": 365 },
        "features": { "enabled": true, "available": ["analytics", "export", "api-access"] },
        "keyFormat": {
          "prefix": "VIG",
          "segments": 4,
          "segmentLength": 4,
          "separator": "-",
          "charset": "BASE32"
        }
      },
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "pages": 1 }
}

POST/api/licensing/policiesRequires: manage:license-policies

Eine neue Lizenzrichtlinie erstellen.

Anfragekörper


{
  "name": "Pro Plan",
  "slug": "pro-plan",
  "validationMode": "HYBRID",
  "dimensions": {
    "seats": { "enabled": true, "defaultMax": 5 },
    "devices": { "enabled": true, "defaultMax": 3 },
    "expiry": { "enabled": true, "defaultDays": 365 },
    "features": { "enabled": true, "available": ["analytics", "export"] },
    "keyFormat": {
      "prefix": "VIG",
      "segments": 4,
      "segmentLength": 4,
      "separator": "-",
      "charset": "BASE32"
    }
  }
}

Feld	Typ	Erforderlich	Beschreibung
`name`	`string`	Ja	Anzeigename
`slug`	`string`	Ja	Eindeutiger Slug (z. B. `pro-plan`)
`validationMode`	`ONLINE \| HYBRID \| OFFLINE`	Nein	Standard: `HYBRID`
`dimensions`	`object`	Nein	Konfiguration für Plätze, Geräte, Funktionen, Ablauf und Schlüsselformat
`offlineGraceDays`	`number`	Nein	Tage, die ein Schlüssel offline gültig bleibt (Standard: 7)
`revocationTtlMin`	`number`	Nein	Minuten bis zur Verbreitung des Widerrufs (Standard: 60)

GET/api/licensing/policies/:idRequires: manage:license-policies

Eine einzelne Richtlinie anhand der ID abrufen.

PATCH/api/licensing/policies/:idRequires: manage:license-policies

Eine Richtlinie aktualisieren. Nur angegebene Felder werden geändert.

DELETE/api/licensing/policies/:idRequires: manage:license-policies

Eine Richtlinie löschen. Schlägt fehl, wenn noch Schlüssel unter dieser Richtlinie ausgestellt sind.

Schlüssel

Schlüssel werden gegen eine Richtlinie ausgestellt und einem Lizenznehmer (Benutzer, Organisation oder Gerät) zugewiesen.

GET/api/licensing/keysRequires: manage:license-keys

Alle Schlüssel auflisten. Filterbar nach Status und Richtlinie.

Abfrageparameter

Parameter	Typ	Beschreibung
`page`	`number`	Seitennummer
`limit`	`number`	Einträge pro Seite
`policyId`	`string`	Nach Richtlinie filtern
`status`	`ACTIVE \| SUSPENDED \| REVOKED \| EXPIRED`	Nach Status filtern

POST/api/licensing/keysRequires: manage:license-keys

Einen neuen Lizenzschlüssel ausstellen.

Anfragekörper


{
  "policyId": "pol_abc123",
  "licenseeType": "USER",
  "licenseeId": "user_xyz789",
  "notes": "Issued via Stripe checkout"
}

Antwort enthält das vollständige Schlüsselobjekt mit key (die Lizenzzeichenkette) und jwtToken (für Offline-Validierung).

GET/api/licensing/keys/:idRequires: manage:license-keys

Einen einzelnen Schlüssel anhand der ID abrufen, einschließlich zugehöriger Richtlinie, Plätze und Geräte.

POST/api/licensing/keys/:id/suspendRequires: manage:license-keys

Einen Schlüssel sperren. Er kann später reaktiviert werden.

POST/api/licensing/keys/:id/revokeRequires: manage:license-keys

Einen Schlüssel dauerhaft widerrufen.

POST/api/licensing/keys/:id/reissueRequires: manage:license-keys

Einen Schlüssel mit aktualisierten Berechtigungen neu ausstellen. Der alte Schlüssel wird widerrufen und ein neuer generiert.

Optionaler Körper


{
  "features": ["analytics", "export", "api-access"],
  "seatMax": 10,
  "deviceMax": 5,
  "expiresAt": "2027-03-15T00:00:00Z"
}

Plätze

GET/api/licensing/keys/:id/seatsRequires: manage:license-keys

Alle Plätze (zugewiesene Benutzer) für einen Schlüssel auflisten.

POST/api/licensing/keys/:id/seatsRequires: manage:license-keys

Einem Benutzer einen Platz zuweisen. Schlägt fehl, wenn das Platzlimit erreicht ist.


{ "userId": "user_abc" }

DELETE/api/licensing/keys/:id/seats/:userIdRequires: manage:license-keys

Einen Platz von einem Benutzer freigeben.

Geräte

GET/api/licensing/keys/:id/devicesRequires: manage:license-keys

Alle aktivierten Geräte für einen Schlüssel auflisten.

DELETE/api/licensing/keys/:id/devices/:deviceIdRequires: manage:license-keys

Ein Gerät von einem Schlüssel entfernen.

Validierung (Öffentlich)

Diese Endpunkte werden von deiner Anwendung zur Laufzeit aufgerufen. Es ist kein Bearer-Token erforderlich.

POST/api/licensing/validate

Einen Lizenzschlüssel online validieren. Gibt Gültigkeit, Funktionen, Platz-/Geräteanzahl und Ablauf zurück.

Anfragekörper


{ "key": "VIG-A8BC-D3EF-G4HJ-K5LM" }

Erfolgsantwort


{
  "valid": true,
  "features": ["analytics", "export"],
  "seats": { "used": 2, "max": 5 },
  "devices": { "used": 1, "max": 3 },
  "expiresAt": "2027-01-15T00:00:00Z"
}

Antwort bei ungültigem Schlüssel


{
  "valid": false,
  "reason": "REVOKED"
}

Mögliche reason-Werte: INVALID, EXPIRED, REVOKED, SUSPENDED, SEAT_LIMIT, DEVICE_LIMIT.

Geräteaktivierung (Öffentlich)

POST/api/licensing/activate

Ein Gerät gegen einen Lizenzschlüssel registrieren. Verwende dies beim ersten Start einer Desktop-/Mobilanwendung.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6",
  "name": "John's MacBook Pro"
}

Gibt 200 bei Erfolg zurück. Wirft 409, wenn das Gerätelimit erreicht ist.

POST/api/licensing/deactivate

Ein Gerät von einem Schlüssel entfernen. Verwende dies, wenn sich der Benutzer abmeldet oder die App deinstalliert.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "fingerprint": "a1b2c3d4e5f6"
}

Nutzungsverfolgung (Öffentlich)

POST/api/licensing/usage

Eine Nutzungsmetrik gegen einen Schlüssel erfassen. Nützlich für verbrauchsbasierte Lizenzierung.


{
  "key": "VIG-A8BC-D3EF-G4HJ-K5LM",
  "metric": "api_calls",
  "amount": 1
}

GET/api/licensing/usage/:key

Aktuelle Nutzungsdaten für einen Schlüssel über alle Metriken abrufen.

Widerrufsliste (Öffentlich)

GET/api/licensing/revocation-list

Gibt ein signiertes JWT zurück, das alle widerrufenen Schlüssel-JTIs enthält. Wird vom SDK zur Offline-Widerrufsprüfung verwendet.

Die Antwort ist application/jwt mit Cache-Control: public, max-age=3600. Das SDK ruft diese automatisch ab.

Automatisierungsregeln

Automatisierungsregeln verbinden Zahlungsereignisse (Stripe, PayPal) mit Lizenzaktionen (Ausstellen, Aktivieren, Sperren, Widerrufen).

GET/api/licensing/automationRequires: manage:license-policies

Alle Automatisierungsregeln auflisten.

POST/api/licensing/automationRequires: manage:license-policies

Eine neue Automatisierungsregel erstellen.


{
  "name": "Stripe checkout → issue key",
  "provider": "stripe",
  "triggerEvent": "checkout.session.completed",
  "action": "issue_key",
  "policyId": "pol_abc123",
  "isActive": true
}

Anbieter	Auslösende Ereignisse
`stripe`	`checkout.session.completed`, `invoice.paid`, `payment_intent.succeeded`
`paypal`	`PAYMENT.CAPTURE.COMPLETED`
`manual`	`manual_trigger`

Aktion	Beschreibung
`issue_key`	Einen neuen Schlüssel unter der verknüpften Richtlinie ausstellen
`activate_key`	Einen vorhandenen Schlüssel aktivieren
`suspend_key`	Einen Schlüssel sperren
`revoke_key`	Einen Schlüssel widerrufen

GET/api/licensing/automation/:idRequires: manage:license-policies

Eine einzelne Automatisierungsregel abrufen.

PATCH/api/licensing/automation/:idRequires: manage:license-policies

Eine Automatisierungsregel aktualisieren.

DELETE/api/licensing/automation/:idRequires: manage:license-policies

Eine Automatisierungsregel löschen.

Webhooks

Diese Endpunkte empfangen Ereignisse von Zahlungsanbietern. Sie werden per Signatur verifiziert und erfordern kein Bearer-Token.

POST/api/licensing/webhooks/stripe

Empfängt Stripe-Webhook-Ereignisse. Verifizierung über den stripe-signature-Header. Setze STRIPE_LICENSING_WEBHOOK_SECRET in deiner Umgebung.

POST/api/licensing/webhooks/paypal

Empfängt PayPal-Webhook-Ereignisse. Verifizierung über HMAC-SHA256. Setze PAYPAL_LICENSING_WEBHOOK_SECRET und PAYPAL_LICENSING_WEBHOOK_ID in deiner Umgebung.

Statistiken

GET/api/licensing/statsRequires: view:license-stats

Gibt aggregierte Lizenzierungsstatistiken zurück.


{
  "success": true,
  "data": {
    "totalPolicies": 3,
    "totalKeys": 142,
    "activeKeys": 98,
    "revokedKeys": 12,
    "suspendedKeys": 5,
    "expiredKeys": 27,
    "policyDistribution": [
      { "policyId": "pol_abc", "policyName": "Pro Plan", "count": 80 }
    ],
    "recentKeys": []
  }
}