API-Schlüssel und Audit-Logs

ProcureSwift stellt eine REST-API bereit, über die Drittsysteme Beschaffungsdaten programmatisch lesen und schreiben können. Der Zugriff wird durch API-Schlüssel gesteuert — langlebige Geheimnisse, die einem Mandanten zugeordnet, auf bestimmte Ressourcen beschränkt und pro Minute ratenbegrenzt sind. Jeder Aufruf, der mit einem API-Schlüssel erfolgt, wird in den API-Auditprotokollen aufgezeichnet, sodass Administratoren genau nachvollziehen können, was von welchem Schlüssel ausgeführt wurde.

Wo zu finden

• API-Schlüssel: Hauptmenü → API-Schlüssel (/api-keys).
• API-Auditprotokolle: Hauptmenü → API-Auditprotokolle (/api-audit-logs).

Beide Seiten erfordern die Berechtigung ApiKeys / View. Das Erstellen, Widerrufen und Löschen von Schlüsseln erfordern jeweils ApiKeys / Create, ApiKeys / Manage und ApiKeys / Delete.

API-Schlüssel erstellen

1. API-Schlüssel öffnen und auf API-Schlüssel erstellen klicken.
2. Das Formular ausfüllen:
   • Name — eine Bezeichnung, die angibt, wofür dieser Schlüssel verwendet wird (z. B. Xero sync oder Internal data export). Pflichtfeld.
   • Berechtigungen (Scopes) — die Ressourcen und Aktionen auswählen, die dieser Schlüssel ausführen darf. Alle Felder leer lassen, um dem Schlüssel alle Scopes zu gewähren. Verfügbare Scopes:
     • purchase_orders:read, purchase_orders:write
     • invoices:read, invoices:write
     • catalog:read
     • delivery_notes:read, delivery_notes:write
     • quotations:read, quotations:write
     • proposals:read, proposals:write
     • rfqs:read, rfps:read
     • webhooks:manage
   • Ablauf (optional) — optionales Datum, nach dem der Schlüssel nicht mehr gültig ist. Leer lassen für einen unbefristet gültigen Schlüssel.
   • Limit / Min. — maximale Anzahl von Anfragen, die dieser Schlüssel pro Minute stellen darf. Standardwert ist 100. Der Bereich liegt zwischen 1 und 10000.
3. Auf Erstellen klicken.

Einmalige Anzeige des Geheimnisses

Unmittelbar nach der Erstellung wird der vollständige API-Schlüssel einmalig in einem Bestätigungsdialog angezeigt. Kopieren Sie ihn jetzt und speichern Sie ihn in einem Passwort-Manager oder einem Secret Vault — die Plattform zeigt ihn danach nicht mehr an. Wenn der Schlüssel verloren geht, muss er widerrufen und ein neuer erstellt werden.

In der Schlüsselliste wird anschließend nur noch das Schlüssel-Präfix (die ersten paar Zeichen) angezeigt, damit der Schlüssel in Logs erkennbar ist, ohne das vollständige Geheimnis preiszugeben.

Vorhandene Schlüssel verwalten

Die Tabelle Aktive Schlüssel auf /api-keys zeigt: Name, Schlüsselpräfix, Berechtigungen (Scopes), Läuft ab, Status, Zuletzt verwendet, Rate-Limit, Erstellt.

Aktionen pro Zeile:

• Widerrufen (Sperren-Symbol) — deaktiviert den Schlüssel sofort. Zukünftige Anfragen mit diesem Schlüssel werden abgelehnt. Widerrufene Schlüssel verbleiben mit dem Status Widerrufen in der Liste, um die Nachvollziehbarkeit zu gewährleisten.
• Löschen (Papierkorb-Symbol) — entfernt den Schlüsseleintrag dauerhaft. Verwenden Sie diese Option zur Bereinigung, nachdem ein widerrufener Schlüssel das aktive Log-Aufbewahrungsfenster überschritten hat.

Ein Schlüssel, der sein Ablaufdatum erreicht hat, wird automatisch inaktiv — die Spalte Läuft ab wird in Rot angezeigt.

API-Schlüssel verwenden

Den Schlüssel im Header Authorization jeder API-Anfrage übergeben:

Authorization: ApiKey <your-key>

Zusammen mit der Mandantenkennung im Header tenant reicht dies aus, damit der Server die Anfrage authentifiziert und dem richtigen Mandanten zuordnet.

API-Auditprotokolle

Die Seite API-Auditprotokolle zeichnet jede HTTP-Anfrage auf, die mit einem API-Schlüssel durchgeführt wurde. Jede Zeile zeigt:

• API-Schlüssel — Name des verwendeten Schlüssels.
• Methode — HTTP-Methode (GET / POST / PUT / DELETE), farblich hervorgehoben.
• Pfad — der aufgerufene Endpunkt.
• Status — HTTP-Statuscode, nach Klasse eingefärbt (2xx grün, 4xx gelb, 5xx rot).
• IP-Adresse — die Client-IP-Adresse, von der der Aufruf stammte.
• Dauer — Dauer des Aufrufs in Millisekunden.
• Zeitstempel — Zeitpunkt des Aufrufs.

Mit dem Dropdown Nach API-Schlüssel filtern kann das Log auf einen einzelnen Schlüssel eingeschränkt werden.

Das Log ist paginiert (standardmäßig 25 Zeilen pro Seite) und nach dem neuesten Eintrag zuerst sortiert.

Tipps

• Pro Integration einen eigenen Schlüssel erstellen, nicht einen gemeinsam genutzten Schlüssel für alles — so wird durch das Widerrufen einer kompromittierten Integration keine andere beeinträchtigt.
• Enge Scopes setzen. Ein schreibgeschütztes Export-Skript sollte nur :read-Scopes erhalten.
• Das Rate-Limit nutzen, um sowohl die Plattform als auch das Drittsystem zu schützen. Ein fehlerhaftes Skript, das die API in einer engen Schleife aufruft, lässt sich viel einfacher diagnostizieren, wenn es 429 Too Many Requests erhält, anstatt eine Abhängigkeit zum Absturz zu bringen.
• Das Audit-Log regelmäßig auf unerwartete Pfade oder 4xx/5xx-Häufungen prüfen — diese sind oft ein Hinweis auf eine Integration, die Wartung benötigt.

Berechtigungen

Aktion	Erforderliche Berechtigung
Schlüssel anzeigen, Audit-Log anzeigen	ApiKeys / View
Neuen Schlüssel erstellen	ApiKeys / Create
Schlüssel widerrufen	ApiKeys / Manage
Schlüssel löschen	ApiKeys / Delete

Verwandte Anleitungen

• Webhooks — für den Empfang von Echtzeit-Ereignisbenachrichtigungen der Plattform.