Authentifizierung · TradeCatalog-Dokumentation

Die API verwendet geheime API-Schlüssel. Jeder Schlüssel gehört einem Arbeitsbereich.

Schlüssel sendenLink zu diesem Abschnitt#

Geben Sie den Schlüssel als Bearer-Token im Authorization-Header ein:

http

GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…

bash

curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"

Schlüssel beginnen immer mit tc_live_. Es gibt keine Testschlüssel: Probieren Sie Dinge auf einem Arbeitsbereich mit Beispieldaten aus, oder lesen Sie, bevor Sie schreiben.

Schlüssel erstellenLink zu diesem Abschnitt#

Nur der Besitzer des Arbeitsbereichs oder ein Administrator können Schlüssel erstellen, in Einstellungen → API.

Einstellung	Was es bedeutet
Name	Ihr Label, z. B. „Sage Stock Sync“. Wird in den Einstellungen und im Aktivitätsprotokoll angezeigt.
Nur Lesen	Nur `GET`-Anfragen.
Lesen & Schreiben	Auch `PUT /products`, `PUT /customers` und `PATCH /orders/{id}`.

Der Schlüssel wird einmal angezeigt. Wir speichern nur einen SHA-256-Hash, sodass niemand bei TradeCatalog ihn erneut sehen kann. Die Einstellungen zeigen die ersten Zeichen (wie tc_live_Xk2m…), damit Sie Schlüssel unterscheiden können.

Ein Arbeitsbereich kann bis zu 20 aktive Schlüssel haben. Geben Sie jedem System seinen eigenen Schlüssel, damit Sie einen Schlüssel widerrufen können, ohne die anderen zu beeinträchtigen.

Wer Schlüssel haben kannLink zu diesem Abschnitt#

Der Arbeitsbereich benötigt eines dieser, um Schlüssel zu erstellen:

ein aktives Abonnement
ein Pro-Testzugang
ein Pilotkonto (mit Happy Webs vereinbart)

Demo-Workspaces können keine Schlüssel erstellen oder verwenden.

Wenn das Abonnement abläuft, erhalten Sie 14 Tage Frist. Danach kehrt das Workspace in den Free-Modus zurück. Bestehende Schlüssel können weiterhin lesen, aber API-Schreibvorgänge schlagen mit 403 read_only fehl, bis Pro wieder aktiviert ist. Katalogbearbeitungen und Käuferbestellungen in der App funktionieren weiter.

Was ein Schlüssel tun kannLink zu diesem Abschnitt#

Ein Schlüssel handelt mit den Berechtigungen der Person, die ihn erstellt hat, wie sie aktuell sind. Ein Schlüssel, der von einem Besitzer oder Administrator erstellt wurde, kann jeden Kunden, jeden Kundenpreis, jede Bestellung und den Aktivitätsprotokoll einsehen. Behandeln Sie ihn wie das Passwort dieser Person. Ein Schlüssel, der von jemandem erstellt wurde, der nur auf seine zugewiesenen Kunden oder Regionen beschränkt ist, sieht nur diese Kunden und deren Bestellungen, Preise und Aktivitäten; alle anderen Kunden oder Bestellungen geben 404 zurück, genau wie bei einem, der nicht existiert, und Preisanpassungen geben 403 zurück.

Wenn diese Person später eine engere Rolle erhält, wird der Schlüssel entsprechend angepasst: Ein Schreibvorgang, den die neue Rolle nicht erlaubt, schlägt mit 403 forbidden fehl, genau wie in der App. Wenn sie das Workspace verlässt, funktioniert der Schlüssel nicht mehr mit 401 key_owner_removed. Erstellen Sie einen neuen Schlüssel von jemandem, der weiterhin Zugriff hat.

Letzte Verwendung und WiderrufLink zu diesem Abschnitt#

Die Einstellungen zeigen an, wann jeder Schlüssel zuletzt verwendet wurde (wird maximal einmal pro Stunde aktualisiert). Wählen Sie Widerrufen, um einen Schlüssel sofort zu deaktivieren. Der nächste Antrag mit diesem Schlüssel erhält 401 unauthorized. Widerrufene Schlüssel können nicht wiederhergestellt werden.

Wer die Änderungen im Protokoll einträgtLink zu diesem Abschnitt#

Schreibvorgänge werden im Aktivitätsprotokoll des Workspaces als API key “Sage stock sync” angezeigt. Änderungen des Bestellstatus werden gegen die Person eingetragen, die den Schlüssel erstellt hat.

Schlüssel sicher aufbewahrenLink zu diesem Abschnitt#

Bewahren Sie Schlüssel auf Ihrem Server, in Umgebungsvariablen oder einem Secrets Manager auf.
Geben Sie niemals einen Schlüssel in eine Webseite, Browser-Erweiterung oder Mobile App ein. Aus diesem Grund erlaubt die API keine CORS-Anfragen von Browsern.
Committen Sie niemals einen Schlüssel in git. Falls Sie es dennoch tun, widerrufen Sie ihn und erstellen Sie einen neuen.
Verwenden Sie immer einen Lese-Schlüssel, wenn Sie nur lesen müssen.

FehlerLink zu diesem Abschnitt#

Status	Code	Warum
401	`unauthorized`	Kein `Authorization`-Header, ein fehlerhafter Header, ein unbekannter oder widerrufener Schlüssel oder ein Demo-Workspace. Die Antwort enthält `WWW-Authenticate: Bearer`.
401	`key_owner_removed`	Die Person, die den Schlüssel erstellt hat, hat keinen Zugriff mehr auf das Workspace. Erstellen Sie einen neuen Schlüssel.
403	`insufficient_scope`	Ein Lese-Schlüssel hat versucht, zu schreiben.
403	`forbidden`	Die Person, die den Schlüssel erstellt hat, ist nicht berechtigt, dies zu tun (z. B. ein Viewer kann nicht schreiben).
403	`read_only`	API-Schreibvorgänge sind auf dem Free-Plan nicht verfügbar.

Siehe Fehler für die vollständige Liste.

AI-Apps verwenden eine andere Anmeldung

Claude, ChatGPT und andere MCP-Clients verwenden keine API-Schlüssel. Jeder Benutzer meldet sich mit seinem eigenen Login über OAuth an. Siehe MCP.