Wie verwende ich die Licensing-API, um Lizenzen programmgesteuert zu verwalten?

Lerne, wie du die SecureMailMerge Licensing REST API nutzt, um Lizenzen programmatisch mit API-Schlüsseln zu vergeben und zu entziehen.

Der Lizenzserver bietet eine REST-API, mit der du Lizenzen programmgesteuert zuweisen und entziehen kannst. Das ist praktisch für Wiederverkäufer, die mehrere Kunden verwalten, IT-Teams, die die Einarbeitung automatisieren, oder für alle, die das Lizenzmanagement in ihre eigenen Tools integrieren möchten.

Authentifizierung und Basis-URL

Alle API-Anfragen werden mit einem API-Schlüssel authentifiziert. Der API-Schlüssel ist eine GUID, die du im Anfragekörper (nicht im Header) einfügst.

Alle API-Endpunkte sind verfügbar unter:

https://licensing.solinventum.com/api/manage/{subscriptionType}/{subscriptionID}

Dabei gilt:

• subscriptionType ist eines von: Paddle, Azure oder Manual
• subscriptionID ist die GUID deines Abonnements

Du musst diese URL nicht selbst zusammenstellen. Gehe auf dem Lizenzserver zur Seite „Lizenzen zuweisen“ deines Abonnements und wähle den Tab Lizenzen über API zuweisen. Dort findest du die vollständige Basis-URL, deinen API-Schlüssel und eine einsatzbereite JSON-Nutzlast für dein Abonnement.

Deinen API-Schlüssel neu generieren

Wenn dein API-Schlüssel kompromittiert wurde, kannst du ihn auf derselben Seite neu generieren. Der alte Schlüssel wird sofort ungültig. Nur der Abonnementbesitzer kann API-Schlüssel neu generieren. Verwende immer HTTPS beim Aufrufen der API und halte deinen API-Schlüssel geheim – jeder mit deinem API-Schlüssel kann Lizenzen in deinem Abonnement zuweisen und entfernen.

Lizenzen zuweisen

Füge Lizenzzuweisungen für eine oder mehrere E-Mail-Adressen hinzu.

PUT /api/manage/{subscriptionType}/{subscriptionID}
Content-Type: application/json

Anfrageinhalt

{
  "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
  "emails": ["user1@example.com", "user2@example.com"]
}

Antwort

Erfolg (200):

{
  "success": true,
  "errors": [],
  "assignmentStats": {
    "availableLicenses": 10,
    "assignedLicenses": 7
  }
}

Unzureichende Lizenzen (402):

Wird zurückgegeben, wenn du versuchst, mehr Lizenzen zuzuweisen, als in deinem Abonnement verfügbar sind.

Fehlerhafte Anfrage (400):

Wird bei Validierungsfehlern wie ungültigem E-Mail-Format, doppelten E-Mails oder fehlenden Feldern zurückgegeben.

Validierungsregeln

• Mindestens eine E-Mail-Adresse muss angegeben werden
• Jede E-Mail muss ein gültiges Format haben und darf nicht länger als 256 Zeichen sein
• Doppelte E-Mails innerhalb derselben Anfrage werden abgelehnt
• Du kannst nicht mehr Lizenzen zuweisen, als in deinem Abonnement verfügbar sind

Beispiele

cURL

curl -X PUT \
  https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
    "emails": ["newuser@example.com"]
  }'

PowerShell

$body = @{
    apiKey = "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df"
    emails = @("newuser@example.com")
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Put `
  -Uri "https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f" `
  -ContentType "application/json" `
  -Body $body

Lizenzen entziehen

Entferne Lizenzzuweisungen von einer oder mehreren E-Mail-Adressen.

DELETE /api/manage/{subscriptionType}/{subscriptionID}
Content-Type: application/json

Anfragetext

{
  "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
  "emails": ["user1@example.com"]
}

Das Format des Anfragetexts ist dasselbe wie beim Zuweisen von Lizenzen.

Antwort

Erfolg (200):

{
  "success": true,
  "errors": [],
  "assignmentStats": {
    "availableLicenses": 10,
    "assignedLicenses": 6
  }
}

Fehlerhafte Anfrage (400):

Wird zurückgegeben, wenn die angegebenen E-Mail-Adressen derzeit nicht dem Abonnement zugewiesen sind.

Beispiel

curl -X DELETE \
  https://licensing.solinventum.com/api/manage/Paddle/ff3d3cf5-5388-40a0-915f-970c1d2d972f \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "4024d0d8-9a7d-4ac3-9e61-efaeb7c278df",
    "emails": ["olduser@example.com"]
  }'

Fehlerbehandlung

Überprüfe immer das success-Feld und das errors-Array im Antwortkörper, um Details darüber zu erhalten, was schiefgelaufen ist.