Persönlicher Zugriffstoken (PAT) – was das ist und wie Sie ihn verwenden#

Was ist ein persönlicher Zugriffstoken (PAT)?#

PAT (vom englischen Personal Access Token, deutsch persönlicher Zugriffstoken) ist eine lange zufällige Zeichenfolge, die als Alternative zum Passwort für den Zugriff auf die Mergado API dient. Der Token repräsentiert Sie und Ihre Berechtigungen – wenn Sie ihn jemandem (oder einer Anwendung) übergeben, kann diese Person bzw. Anwendung in Mergado in dem Umfang Aktionen für Sie ausführen, den Sie dem Token erlaubt haben.

Die Abkürzung PAT verwenden wir, weil sie branchenübergreifend der Standardbegriff ist (GitHub, GitLab, Atlassian u. a.).

Der PAT unterscheidet sich vom Passwort dadurch:

• Er hat einen begrenzten Umfang (Scopes) – Sie wählen aus, was der Token konkret tun darf (z. B. Projekte nur lesen, nicht löschen).
• Er hat eine optionale Gültigkeit – Sie können festlegen, wann der Token aufhört zu funktionieren.
• Er lässt sich jederzeit ungültig machen, ohne dass das Passwort geändert werden muss.
• Mit ihm lassen sich keine Kontoeinstellungen ändern (Änderung von Passwort, E-Mail-Adresse, Abrechnung) – dafür müssen Sie sich auf dem üblichen Weg anmelden.
• Er gibt Ihr Passwort nicht an Dritte weiter, auch wenn Sie den Token übergeben.

Der PAT ist für den Zugriff auf die Mergado Editor API bestimmt. Mit dem Token lässt sich nicht bei weiteren Diensten von Mergado anmelden (Mergado Forum, Mergado Store u. Ä.).

Wann benötige ich einen PAT?#

Typische Szenarien:

• Verknüpfung von Mergado mit KI-Agenten wie ChatGPT, Claude oder Cursor über den Mergado MCP-Server. Die Anleitung finden Sie im Artikel Verbindung von Mergado mit KI-Agenten.
• Eigene Skripte und Automatisierungen – z. B. regelmäßiger Datenexport, Anpassungen von Projekten im Stapel, Integration in interne Systeme.
• Entwicklung und Testen eigener Anwendungen auf Basis der Mergado API.
• Verknüpfung mit No-Code-Werkzeugen wie Zapier, Make, n8n oder Gumloop.

Wie generiere ich einen PAT?#

1. Melden Sie sich im Mergado Editor an.

2. Klicken Sie in der rechten oberen Ecke auf Ihr Profil → API and Access (API und Zugänge).

3. Klicken Sie auf die Schaltfläche + Create token (+ Token erstellen).

4. Benennen Sie den Token mit einer Beschreibung, an der Sie erkennen, wo er verwendet wird – z. B. „Claude Desktop", „Exportskript für die Buchhaltung". Wenn Sie die Token später verwalten, ist der Name der wichtigste Anhaltspunkt, um sie voneinander zu unterscheiden.

5. Stellen Sie die Gültigkeit des Tokens ein. Die Möglichkeiten:

   • 7 Tage
   • 30 Tage
   • 90 Tage
   • 365 Tage
   • Nie (der Token gilt, bis Sie ihn manuell ungültig machen)

   Für Token in der Automatisierung empfehlen wir, eine konkrete Gültigkeit einzustellen (z. B. 90 Tage) – eine regelmäßige Erneuerung verringert die Folgen eines etwaigen Abflusses des Tokens. Für Entwicklung und Testen genügt eine kurze Gültigkeit (7 Tage).

6. Wählen Sie die Berechtigungen (Scopes) – siehe Berechtigungen

7. Klicken Sie auf Create (Erstellen).

8. Kopieren Sie den Token und bewahren Sie ihn an einem sicheren Ort auf (Passwortmanager, verschlüsselte Datei). Nach dem Verlassen der Seite zeigen wir den Token nicht erneut an – wenn Sie ihn verlieren, müssen Sie einen neuen erstellen.

Der Token hat das Präfix mergado_pat_, gefolgt von 60 zufälligen Zeichen, z. B. mergado_pat_aec7bb21ff4b2c09b156cd3130b4eef0daf69ea2e1e0d62c23472626aa7e72314fdbb53896b2fd8046c5.

Tipp: In der Liste der Token sehen Sie eine sogenannte Token-Vorschau im Format mergado_pat_***8046c5, wobei die letzten 6 Zeichen der Endung des tatsächlichen Tokens entsprechen. So können Sie schnell überprüfen, welcher Token welcher ist, ohne ihn zur Hand haben zu müssen.

Der Token ist ein sensibler Wert – behandeln Sie ihn wie ein Passwort. Wer über den Token verfügt, hat in Mergado im Umfang der erteilten Scopes dieselben Berechtigungen wie Sie.

Berechtigungen (Scopes)#

Beim Erstellen des Tokens wählen Sie über Kontrollkästchen konkrete Berechtigungen aus. Die Berechtigungen sind in logische Blöcke gruppiert (Benutzer, Onlineshop, Projekt), damit Sie sich leichter in ihnen zurechtfinden.

Empfehlung: Erteilen Sie dem Token nur jene Berechtigungen, die die betreffende Anwendung tatsächlich benötigt. Wenn ein Skript zum Beispiel nur Daten aus einem Projekt liest, benötigt es weder Schreib- noch Löschrechte. Dieses Prinzip nennt man Prinzip der geringsten Rechte (least privilege).

Benutzer#

Berechtigungen, die Ihr Benutzerkonto und Informationen über Sie betreffen.

Onlineshop#

Berechtigungen für die Daten eines konkreten Onlineshops.

Projekt#

Berechtigungen für die einzelnen Projekte (Exporte) innerhalb eines Onlineshops. Diese Gruppe ist die umfangreichste – ein Projekt enthält Regeln, Abfragen, Produkte, Statistiken usw., und jede dieser Ebenen hat eigene Berechtigungen für Lesen und Schreiben.

Für Entwickler: Die technischen Bezeichnungen (IDs) der einzelnen Scopes im API-Format (z. B. project.rules.write) finden Sie in der API-Dokumentation zu OAuth Scopes.

In der Liste der Token sehen Sie bei jeder Zeile die Anzahl der erteilten Berechtigungen und können sie mit einem Klick auf Show (Anzeigen) als Tags aufklappen.

Wie verwende ich den Token?#

Der Token wird im Header der HTTP-Anfrage als Bearer Token gesendet:

Authorization: Bearer <Ihr-Token>

Beispiel für einen API-Aufruf über curl:

curl -H "Authorization: Bearer mergado_pat_..." \
     https://api.mergado.com/me

Eine vollständige Beschreibung aller Endpunkte finden Sie in der API-Dokumentation:

• API-Referenz: api-docs.mergado.com
• Vorgehen bei der Autorisierung: mergado.github.io/docs/api/authorization.html

Sicherheit und Verwaltung der Token#

Was Sie tun sollten#

• Bewahren Sie den Token in einem Passwortmanager oder in einer verschlüsselten Konfiguration auf (z. B. Umgebungsvariable, Secret Manager).
• Erstellen Sie für jede Anwendung bzw. Integration einen eigenen Token mit eigenem Namen. So lässt sich eine konkrete Integration leichter ungültig machen, ohne die übrigen zu beeinträchtigen.
• Erteilen Sie dem Token nur jene Berechtigungen, die er benötigt (Prinzip der geringsten Rechte).
• Gehen Sie die Liste der aktiven Token regelmäßig durch und machen Sie jene ungültig, die Sie nicht mehr nutzen.
• Stellen Sie für Token in der Automatisierung eine Gültigkeit von 90 Tagen ein und erneuern Sie den Token periodisch.

Was Sie nicht tun sollten#

• Committen Sie den Token nicht nach Git und in kein anderes Repository. Sollte das versehentlich geschehen, machen Sie den Token sofort ungültig – die Git-Historie ist auch nach dem Löschen der Datei öffentlich zugänglich.
• Senden Sie den Token nicht per E-Mail, Slack, Teams oder andere Chat-Anwendungen im Klartext.
• Teilen Sie einen Token nicht zwischen mehreren Personen oder Anwendungen.

Was bei einer Kompromittierung zu tun ist#

Wenn Sie den Verdacht haben, dass Ihr Token in unbefugte Hände geraten ist (z. B. versehentlich in einem Repository oder Screenshot veröffentlicht, verdächtige Aktivität im Konto):

1. Gehen Sie sofort in API and Access und machen Sie den Token ungültig (Papierkorbsymbol in der Liste).
2. Erstellen Sie einen neuen Token und aktualisieren Sie ihn in allen Integrationen, in denen er verwendet wurde.

FAQ#

Ich habe den Token verloren, was jetzt?#

Wir zeigen den Token nicht erneut an. Erstellen Sie einen neuen und aktualisieren Sie ihn in der Anwendung, in der er verwendet wurde. Den alten Token sollten Sie ungültig machen, damit er sich nicht missbrauchen lässt, falls ihn jemand später findet.

Wie viele Token kann ich haben?#

Die Anzahl der persönlichen Zugriffstoken pro Nutzer ist aktuell nicht begrenzt. Wir empfehlen jedoch, für jede Integration einen eigenen Token zu erstellen – so lassen sie sich leichter verwalten, und bei Bedarf lässt sich eine konkrete Integration durch das Ungültigmachen eines einzigen Tokens abkoppeln.

Wie lange ist ein Token gültig?#

So lange, wie Sie es bei seiner Erstellung eingestellt haben – 7, 30, 90, 365 Tage oder Nie. Das aktuelle Ablaufdatum sehen Sie in der Liste der Token in der Spalte Expires (Läuft ab). Nach dem Ablauf funktioniert der Token nicht mehr, und Sie müssen einen neuen erstellen.

Die API gibt mir 401 Unauthorized zurück. Was nun?#

• Prüfen Sie, dass Sie den Token vollständig und ohne Leerzeichen am Anfang/Ende kopieren.
• Prüfen Sie das Format des Headers: Authorization: Bearer <Token> (das Wort Bearer wird durch ein Leerzeichen abgetrennt).
• Der Token wurde möglicherweise ungültig gemacht oder ist abgelaufen – prüfen Sie in der Liste der Token die Spalte Expires.
• Wenn der Token in der Liste vollständig fehlt, wurde er gelöscht – erstellen Sie einen neuen.

Die API gibt mir 403 Forbidden zurück. Was nun?#

Der Token ist gültig, hat aber keine Berechtigung für die betreffende Aktion. Prüfen Sie in der Liste der Token seine Berechtigungen (Spalte Scopes → Show) und erstellen Sie bei Bedarf einen neuen mit erweiterten Scopes. Ein bestehender Token lässt sich nicht erweitern – aus Sicherheitsgründen müssen Sie einen neuen erstellen.

Kann ich den Token für die Anmeldung im Mergado Forum oder im Mergado Store verwenden?#

Nein. Der PAT ist ausschließlich für die Mergado Editor API bestimmt. Bei den übrigen Diensten von Mergado melden Sie sich wie gewohnt über das Mergado-Konto an.

Kann ich den PAT in meiner Anwendung nutzen, die ich Kunden bereitstelle?#

Nein. Der PAT repräsentiert einen konkreten Nutzer. Wenn Sie eine Anwendung entwickeln, die Kunden von Mergado nutzen werden, verwenden Sie den OAuth-Flow – jeder Nutzer autorisiert sich selbst unter seinem Konto. Mehr in der API-Dokumentation.

Verwandte Links#

• API and Access – Verwaltung der persönlichen Zugriffstoken
• Verbindung von Mergado mit KI-Agenten (ChatGPT, Claude, Cursor)
• API-Referenz: api-docs.mergado.com
• Vorgehen bei der Autorisierung: mergado.github.io/docs/api/authorization.html