> ## Documentation Index
> Fetch the complete documentation index at: https://www.zippendo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentifizierung

> Wie der Zippendo-MCP-Server deinen KI-Agenten per OAuth 2.1 anmeldet und wie du die Organisation und die Berechtigungen festlegst, die er erhält.

Du entscheidest genau, was ein verbundener KI-Agent in Zippendo tun darf: in welcher Organisation er arbeitet und welche Berechtigungen er hat. Die Connector-URL (`https://api.zippendo.com/mcp`) ist durch **OAuth 2.1** geschützt. Du fügst nie einen Token ein: Dein Client findet die Anmeldung über die URL, öffnet deinen Browser, und du meldest dich bei Zippendo an und genehmigst den Zugriff. Diese Seite erklärt, was passiert und was du steuerst.

## Die Schritte der Verbindung

Wenn du die URL zu einem Client hinzufügst und dich zum ersten Mal verbindest:

<Steps>
  <Step title="Dein Client findet die Anmeldung">
    Der Server beantwortet die erste Anfrage ohne Zugangsdaten mit einem Verweis auf seine OAuth-Details. Dein Client registriert sich automatisch (du musst keine Client-ID erstellen) und öffnet deinen Browser.
  </Step>

  <Step title="Du meldest dich bei Zippendo an">
    Bist du noch nicht angemeldet, landest du auf der Zippendo-Anmeldeseite. Melde dich wie gewohnt an.
  </Step>

  <Step title="Du genehmigst den Zugriff auf dem Zustimmungsbildschirm">
    Der Bildschirm **Authorize access** zeigt den Namen des Clients, die **Organization**, die verbunden werden soll, und die **Permissions**, die er anfragt. Wähle die Organisation, aktiviere die Berechtigungen, die du erteilen möchtest, und klicke auf **Authorize**. Klicke auf **Deny**, um abzulehnen.
  </Step>

  <Step title="Du bist verbunden">
    Der Browser gibt die Kontrolle an deinen Client zurück, der seine Token speichert und selbst erneuert. Du musst dich nicht erneut anmelden, bis du den Agenten trennst oder sein Zugriff abläuft.
  </Step>
</Steps>

<Note>
  Ein Teammitglied, das auf eine Marke beschränkt ist, kann keinen Agenten verbinden. Der Zustimmungsbildschirm lehnt die Anfrage ab. Bitte jemanden mit Zugriff auf die gesamte Organisation, ihn zu verbinden.
</Note>

## Eine Organisation wählen

Jede Verbindung gehört zu **einer Organisation**. Auf dem Zustimmungsbildschirm wählst du, in welcher Organisation der Agent arbeiten darf, und jeder Tool-Aufruf bleibt innerhalb dieser Organisation.

Um in einer anderen Organisation zu arbeiten, verbinde dich erneut und wähle auf dem Zustimmungsbildschirm die andere Organisation. In Clients, die mehr als einen Servereintrag erlauben, kannst du auch einen zweiten Connector mit derselben URL hinzufügen und ihn für die andere Organisation genehmigen.

## Berechtigungen einschränken

Auf dem Zustimmungsbildschirm kannst du **weniger** Berechtigungen erteilen, als der Client anfragt, aber nie mehr. Mindestens eine musst du behalten. Fragt der Client keine bestimmte an, bietet der Bildschirm Lese- und Schreibzugriff auf alles an. Erteile nur, was der Agent braucht:

* Soll er nur Fragen beantworten? Erteile nur die **Read**-Berechtigungen.
* Soll er Sendungen erstellen und senden? Füge Schreibzugriff auf Sendungen hinzu (`write:shipments`).

Die Tools, die dein Agent sieht, werden auf die Berechtigungen gefiltert, die du genehmigst. Die vollständige Zuordnung findest du unter [Tools und Scopes](/docs/de/mcp/tools).

<Info>
  Der Agent handelt **als du**, nur in der Organisation und mit den Berechtigungen, die du genehmigt hast, und **nie** mit den Rechten von Zippendo-Mitarbeitern. Jeder Tool-Aufruf durchläuft dieselbe Anmeldung, dieselben Berechtigungsprüfungen, Tarif-Limits und Validierung wie eine normale API-Anfrage.
</Info>

## Token und Erneuerung

Dein Client verwaltet die OAuth-Token für dich:

| Token | Lebensdauer | Hinweise |
| - | - | - |
| Access-Token | 1 Stunde | Wird bei jeder Anfrage gesendet. |
| Refresh-Token | 30 Tage | Wird bei jeder Verwendung ersetzt. Wird ein altes Refresh-Token erneut verwendet, gilt das als Diebstahl und **beendet die gesamte Verbindung**. |

Du musst dich nicht selbst darum kümmern: Der Client speichert und erneuert sie.

## Trennen

Um den Zugriff eines Agenten zu beenden, gehe in der Zippendo-App zu **Apps & integrations**. Die Karte **MCP (AI agents)** listet die Agenten, die du verbunden hast, mit dem Zeitpunkt der letzten Nutzung und der Anzahl ihrer Berechtigungen. Klicke neben dem Agenten auf **Disconnect**. Sein Zugriff endet sofort, einschließlich der Token, die er bereits hält.

Du kannst den Connector auch in deinem Client entfernen (zum Beispiel `claude mcp remove zippendo` oder indem du ihn in den MCP- oder Connector-Einstellungen des Clients löschst). Dadurch kann der Client ihn nicht mehr nutzen, aber nur **Disconnect** in Zippendo macht die Token auf der Seite von Zippendo ungültig.

<Note>
  Die Karte zeigt nur die Agenten, die du selbst verbunden hast. Jedes Teammitglied verbindet und trennt seine eigenen Agenten.
</Note>

## Für Entwickler: Discovery-Endpunkte

Die API ist ihr eigener OAuth-2.1-Autorisierungsserver. Die standardisierten Discovery-Endpunkte sind öffentlich:

| Endpunkt | Zweck |
| - | - |
| `GET /.well-known/oauth-protected-resource` | RFC 9728: verweist Clients auf den Autorisierungsserver. |
| `GET /.well-known/oauth-authorization-server` | RFC 8414: Metadaten des Autorisierungsservers. |
| `POST /oauth/register` | RFC 7591: dynamische Client-Registrierung (öffentliche PKCE-Clients). |
| `GET /oauth/authorize` | Startet die Autorisierung (PKCE S256). |
| `POST /oauth/token` | Tauscht den Code ein und rotiert Refresh-Token. |

Ein konformer MCP-Client erledigt all das für dich: Du gibst ihm nur die URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.