Ihr Abrechnungs- oder CRM-System mit der Uniqkey Partner API verbinden

Uniqkey-Partner können die monatliche Lizenznutzung für alle ihre Kundenorganisationen über eine REST-API auslesen. Dadurch kann ein Abrechnungs-, CRM- oder Berichtssystem die Zahlen direkt abrufen, anstatt dass jemand sie aus dem Partner Portal exportieren muss. Dieser Artikel erklärt, wie Sie im Partner Portal einen API-Schlüssel erstellen, wie die API funktioniert und was Sie von den Daten erwarten können.

Wer kann diese Funktion nutzen?

• Die API ist für Uniqkey-Partner vorgesehen. API-Schlüssel werden im Partner Portal von einem Partnerbenutzer mit der Rolle Admin erstellt. Benutzer mit anderen Rollen sehen die Seite API-Schlüssel nicht.
• Ein Schlüssel gehört zu Ihrem Partnerkonto, nicht zu dem Benutzer, der ihn erstellt hat. Er funktioniert weiterhin, wenn dieser Benutzer das Unternehmen verlässt oder entfernt wird.
• Ein Schlüssel kann Ihr eigenes Partnerkonto und die darunterliegenden Partner in Ihrer Hierarchie sehen. Ein Distributor sieht daher auch die Kunden seiner Wiederverkäufer. Partner über oder neben Ihnen werden niemals angezeigt.
• Ihr System benötigt ausgehenden HTTPS-Zugriff auf https://partner-api-public.production.uniqkey.eu.
• Die API ist schreibgeschützt und gibt Lizenzzahlen sowie Organisationsnamen zurück. Tresordaten, Passwörter, Schlüssel oder Mitarbeiterdetails sind niemals enthalten.

Schritt 1: API-Schlüssel erstellen

1. Melden Sie sich als Admin im Partner Portal an.
2. Öffnen Sie im Menü API-Schlüssel.
3. Klicken Sie auf API-Schlüssel erstellen.
4. Geben Sie einen Namen für die Integration ein, die den Schlüssel verwenden wird, zum Beispiel Abgleich Abrechnung. Der Name wird im Auditprotokoll für alles angezeigt, was der Schlüssel ausführt. Wählen Sie daher einen aussagekräftigen Namen.
5. Wählen Sie optional ein Ablaufdatum aus. Als frühestes Datum kann der morgige Tag ausgewählt werden. Der Schlüssel funktioniert bis zum Ende dieses Tages in der Zeitzone Ihres Browsers. Lassen Sie das Feld leer, wenn der Schlüssel nicht ablaufen soll.
6. Klicken Sie auf Erstellen. Im Dialogfeld API-Schlüssel jetzt kopieren wird der neue Schlüssel angezeigt, der mit uk_p_ beginnt.
7. Kopieren Sie den Schlüssel und speichern Sie ihn im Secrets Store Ihres Systems. Der Schlüssel wird nur einmal angezeigt. Aktivieren Sie Ich habe diesen API-Schlüssel an einem sicheren Ort gespeichert, um das Dialogfeld zu schließen. Danach kann der Schlüssel nicht erneut angezeigt werden. Wenn Sie ihn verlieren, erstellen Sie einen neuen Schlüssel.

Schlüssel später verwalten:

• Auf der Seite API-Schlüssel werden alle Schlüssel mit ihrem Namen, den ersten Zeichen des Schlüssels (damit Sie die Schlüssel unterscheiden können), dem Erstellungsdatum, dem Ablaufdatum, dem Datum der letzten Verwendung und ihrem Status aufgelistet: Aktiv, Abgelaufen oder Widerrufen.
• Um einen Schlüssel zu widerrufen, öffnen Sie das Menü in seiner Zeile, wählen Sie Widerrufen und bestätigen Sie. Der Widerruf ist dauerhaft und kann nicht rückgängig gemacht werden. Der Schlüssel funktioniert sofort nicht mehr; in seltenen Fällen kann dies bis zu 1 Minute dauern. Widerrufene Schlüssel bleiben mit dem Status Widerrufen in der Liste.
• Zuletzt verwendet wird höchstens alle 5 Minuten aktualisiert. Daher kann bei einem aktiv verwendeten Schlüssel eine bis zu 5 Minuten alte Uhrzeit angezeigt werden.
• Ein Ablaufdatum kann nach der Erstellung des Schlüssels nicht geändert werden. Wenn ein Schlüssel bald abläuft, erstellen Sie einen neuen.
• Sie können mehrere Schlüssel erstellen, zum Beispiel einen pro Integration. So können Sie einen Schlüssel widerrufen, ohne die anderen zu beeinflussen. Alle Schlüssel eines Partners teilen sich ein gemeinsames Ratenlimit (siehe „Ratenlimits“).
• So rotieren Sie einen Schlüssel: Erstellen Sie einen neuen Schlüssel, aktualisieren Sie Ihr System, prüfen Sie, ob unter Zuletzt verwendet die Verwendung des neuen Schlüssels angezeigt wird, und widerrufen Sie anschließend den alten Schlüssel.
• Das Erstellen und Widerrufen eines Schlüssels wird im Partner Portal unter Auditprotokolle zusammen mit dem Schlüsselnamen aufgezeichnet. Jede erfolgreiche Lizenzdatenanfrage mit einem Schlüssel wird dort ebenfalls mit dem Schlüsselnamen als Akteur aufgezeichnet. Die Einträge erscheinen im Auditprotokoll des Partners, dem der Schlüssel gehört. Abgelehnte Anfragen und Anfragen an /v1/me werden nicht aufgezeichnet.

Schritt 2: System konfigurieren

Jede Integration benötigt dieselben Angaben:

Die Daten einmal täglich abzurufen, ist eine gute Standardeinstellung. Die Zahlen werden durch einen täglichen Job aktualisiert (siehe „Was Sie von den Daten erwarten können“ weiter unten), daher bringt häufigeres Abrufen keinen Vorteil.

Eine interaktive API-Dokumentation ist unter https://partner-api-public.production.uniqkey.eu/docs verfügbar. Die OpenAPI-Spezifikation, mit der die meisten Tools einen Client generieren können, finden Sie unter https://partner-api-public.production.uniqkey.eu/openapi/v1.json.

Schnelltest mit curl

Prüfen Sie, ob der Schlüssel funktioniert und zu welchem Partner er gehört:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/me" \
  -H "Authorization: Bearer <your key>"

Rufen Sie anschließend die ersten Lizenzzeilen ab:

curl -s "https://partner-api-public.production.uniqkey.eu/v1/licenses?limit=5" \
  -H "Authorization: Bearer <your key>"

Bei einer funktionierenden Konfiguration wird HTTP 200 mit einem JSON-Body wie in den Beispielen im Abschnitt „Antwort“ zurückgegeben. 401 bedeutet, dass der Authorization-Header fehlt, kein Bearer-Token enthält oder der Schlüssel falsch, widerrufen oder abgelaufen ist.

API-Referenz

Anfrage

GET /v1/licenses

Eine Anfrage ohne Parameter ist gültig und gibt jeden Monat jeder Organisation zurück, die der Schlüssel sehen kann, zuerst die neuesten Monate, jeweils eine Seite nach der anderen.

Der Cursor ist opak. Er darf nicht erstellt, analysiert oder geändert werden. Sein Format kann ohne Vorankündigung geändert werden.

GET /v1/me

Akzeptiert keine Parameter. Gibt den Partner zurück, dem der Schlüssel gehört, sowie den eigenen Namen, das Präfix und das Ablaufdatum des Schlüssels. Verwenden Sie den Endpunkt zum Testen eines Schlüssels. Die Anfrage zählt wie jede andere Anfrage zum Ratenlimit.

Antwort

GET /v1/licenses:

{
  "items": [
    {
      "organizationId": "d5ecd732-4a67-418c-9dea-38a097fba1f6",
      "organizationName": "Example Customer ApS",
      "organizationExternalId": "CRM-10442",
      "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
      "partnerName": "Example Reseller A/S",
      "month": "2026-09",
      "usageLicenseCount": 48,
      "committedLicenseCount": 50,
      "discoveryInstallationCount": 12,
      "discoveryActivatedNow": true
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJEIjoiMjAyNi0wOS0wMSIsIk8iOiJkNWVj..."
}

• Die Zeilen sind zuerst nach dem neuesten Monat und anschließend nach organizationId sortiert.
• hasMore gibt an, ob die nächste Seite angefordert werden soll. Wiederholen Sie die Anfrage, solange hasMore den Wert true hat.
• nextCursor ist auf der letzten Seite null.

GET /v1/me:

{
  "partnerId": "3f2a9c1e-7b44-4d0a-9e51-2a6c8f0d1b77",
  "partnerName": "Example Reseller A/S",
  "keyName": "Billing sync",
  "keyPrefix": "uk_p_Xa81kQ2z",
  "expiresAt": "2027-03-31T21:59:59.999Z"
}

expiresAt wird in UTC angegeben und ist bei einem Schlüssel ohne Ablaufdatum null.

Fehler verwenden das standardmäßige Format für Problemdetails (Content-Type: application/problem+json) mit einem stabilen, maschinenlesbaren code:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The request could not be processed.",
  "code": "bad_request",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Richten Sie Ihre Fehlerbehandlung nach code und dem HTTP-Status aus. title und detail sind für Menschen bestimmt und können sich ändern.

Format einer Zeile

Ratenlimits

• Jeder Partner kann mindestens 120 Anfragen pro Minute stellen. Das Limit wird von allen Schlüsseln des Partners gemeinsam genutzt. Durch das Erstellen weiterer Schlüssel wird die Kapazität daher nicht erhöht.
• Wenn das Limit überschritten wird, gibt die API 429 mit dem Code too_many_requests und einem Retry-After-Header zurück, der die Anzahl der zu wartenden Sekunden enthält. Warten Sie mindestens so lange, bevor Sie es erneut versuchen.
• Am Netzwerkrand gilt ein separates, höheres Limit pro Quell-IP-Adresse. Normale Antworten enthalten für dieses Limit X-RateLimit-*-Header. Bei einer Überschreitung erhalten Sie ebenfalls 429, jedoch ohne JSON-Body. Behandeln Sie 429 daher anhand des Status und von Retry-After, statt den Body zu analysieren.

Ein täglicher Abgleich mit limit=1000 benötigt nur wenige Anfragen und bleibt deutlich innerhalb der Limits.

Was Sie von den Daten erwarten können

• Die Zahlen sind monatliche Höchstwerte. usageLicenseCount und discoveryInstallationCount sind die höchsten während des Monats erfassten Tageswerte, nicht ein Durchschnitt oder der Wert am Monatsende. Ein Benutzer, der zwischen zwei Tageserfassungen hinzugefügt und wieder entfernt wird, wird nicht erfasst.
• Die Daten können bis zu einen Tag verzögert sein. Die Zahlen werden von einem täglichen Job erfasst, der kurz nach Mitternacht UTC ausgeführt wird und den vorherigen Tag zählt. Eine heute vorgenommene Änderung wird nach dem nächsten Lauf angezeigt.
• Der aktuelle Monat kann sich noch ändern. Solange der Monat noch nicht vorbei ist, erhöht ein neuer Höchstwert die Zeile des aktuellen Monats. Die letzte Erfassung eines Monats erfolgt in der ersten Stunde des 1. des Folgemonats (UTC). Betrachten Sie einen Monat daher ab 02:00 UTC am 1. als abgeschlossen.
• Jede Organisation erhält für jeden Monat eine Zeile, auch bei einer Nutzung von null. Die Zeilen beginnen in dem Monat, in dem die Organisation erstellt wurde. In seltenen Fällen, etwa bei einem fehlgeschlagenen täglichen Lauf, kann ein Monat für eine Organisation fehlen. Behandeln Sie einen fehlenden Monat als unbekannt, nicht als null.
• Testorganisationen sind enthalten. Für jede Organisation unter Ihrem Partnerkonto werden Zeilen zurückgegeben, unabhängig davon, ob es sich um einen zahlenden Kunden handelt.
• Keine Vereinbarung und eine Vereinbarung von 0 sehen gleich aus. Beide werden als committedLicenseCount: null zurückgegeben.
• discoveryInstallationCount zählt Installationen, nicht Identitäten. Es zählt passive Erweiterungsinstallationen, auf deren Grundlage Discovery lizenziert wird. Die Zahl „Unternehmensidentitäten“ im Discovery-Dashboard zählt etwas anderes und stimmt daher nicht überein.
• discoveryActivatedNow ist kein historischer Wert. Der Wert gibt die heutige Einstellung wieder und wird für jeden Monat wiederholt. Verwenden Sie discoveryInstallationCount für die Abrechnung.
• Namen sind aktuelle Namen. Wenn eine Organisation oder ein Partner umbenannt wird, wird für alle Monate der neue Name angezeigt. Ordnen Sie anhand von organizationId und nicht anhand von Namen zu.
• Gelöschte Organisationen behalten ihre Historie. Vor dem Löschen einer Organisation erfasste Monate werden weiterhin zurückgegeben. Die Zeilen zeigen nicht an, dass die Organisation gelöscht wurde.
• Beim Verschieben einer Organisation wird ihre Historie mitverschoben. Nur Uniqkey kann eine Organisation zu einem anderen Partner verschieben. In diesem Fall werden alle Monate, einschließlich bereits abgerechneter Monate, an den neuen Partner übertragen. Sie verschwinden aus den Ergebnissen des alten Partners, es sei denn, der neue Partner befindet sich unterhalb des alten Partners.

Hinweise für Abrechnungs- und CRM-Integrationen

• Bewahren Sie eine eigene Kopie der abgerechneten Monate auf. Speichern Sie beim Abrechnen die Zeilen jedes Monats in Ihrem System. Aufgrund der oben beschriebenen Verschiebungen und Umbenennungen kann ein Monat, den Sie später erneut abfragen, von dem abweichen, was Sie abgerechnet haben.
• Verwenden Sie organizationId und month als Schlüssel. Jede Organisation hat höchstens eine Zeile pro Monat. Aktualisieren Sie die Zeile bei wiederholten Abgleichen, anstatt Duplikate einzufügen.
• Lesen Sie die letzten Monate erneut ein. Ein einfacher und robuster Abgleich besteht darin, bei jedem Lauf from auf den vorherigen Monat zu setzen und diese Zeilen zu überschreiben. Sperren Sie anschließend einen Monat in Ihrem System, sobald er abgerechnet wurde.
• Ordnen Sie Kunden mit organizationExternalId zu. Öffnen Sie im Partner Portal die Organisation, bearbeiten Sie ihre Details und geben Sie die Kundennummer Ihres CRM unter Externe ID ein. Sie können sie auch beim Erstellen einer Organisation festlegen. Sie wird anschließend in jeder Zeile zurückgegeben. Uniqkey prüft nicht, ob der Wert eindeutig ist.
• Verwenden Sie einen Schlüssel pro System. Ein separater Schlüssel für die Abrechnung und für das CRM macht das Auditprotokoll übersichtlicher und ermöglicht es Ihnen, einen Schlüssel zu widerrufen, ohne das andere System zu beeinträchtigen.

Fehlerbehebung

Wenn Sie den Support kontaktieren, geben Sie Ihre Partner-ID (aus /v1/me), den Schlüsselnamen, die genaue Anfrage-URL ohne den Schlüssel, den HTTP-Status und den Antwort-Body einschließlich der traceId an.