> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Didit MCP-Authentifizierung: Log in with Didit (OAuth) > Authentifizierung des Didit MCP via OAuth 2.1 mit PKCE, dynamischer Client-Registrierung, Scopes, Rollen und Client-Verbindungen. Der Didit MCP authentifiziert sich über **Mit Didit anmelden** (OAuth 2.1). Er agiert als Didit-**Benutzer** mit den Berechtigungen Ihrer Konsolenrolle – **es gibt keinen API-Schlüssel-Modus**. ## Mit Didit anmelden Der gehostete Server (`https://mcp.didit.me/mcp`) ist ein OAuth 2.1 **Resource-Server**. Die **Didit Business Console** (`business.didit.me`) ist der **Autorisierungsserver**, der den Zustimmungsbildschirm hostet und Tokens ausstellt. Ihr MCP-Client führt den Standard-Ablauf automatisch durch: **1. Entdecken** Der Client sendet einen POST-Request an `/mcp` ohne Token und erhält `401` mit einem `WWW-Authenticate: Bearer`-Header, dessen `resource_metadata` auf die Metadaten der geschützten Ressource verweist (RFC 9728): ```text theme={null} https://mcp.didit.me/.well-known/oauth-protected-resource/mcp ``` Dieses Dokument nennt die Ressource (`https://mcp.didit.me/mcp`), den Autorisierungsserver (`https://business.didit.me`) und die unterstützten Scopes. Dasselbe Dokument wird auch am Origin-Root, `https://mcp.didit.me/.well-known/oauth-protected-resource`, für Clients bereitgestellt, die dort zuerst anfragen. **2. Registrieren (dynamische Client-Registrierung)** Der Client liest die Metadaten des Autorisierungsservers unter `https://business.didit.me/.well-known/oauth-authorization-server` und registriert sich, falls er noch keine Client-ID hat, am `registration_endpoint` (RFC 7591). Auf Ihrer Seite muss nichts vorab bereitgestellt werden: Lokale Clients mit einem Loopback- oder nativen Callback (Claude Code, Cursor, MCP Inspector) und Cloud-gehostete Clients mit einem geprüften Callback (Claude) registrieren sich beide auf diese Weise. Eine Remote-Callback-URL, die Didit nicht geprüft hat, wird mit `invalid_redirect_uri` abgelehnt; ein solcher Client muss zuerst von einem Operator registriert werden. **3. Autorisieren (PKCE)** Der Client öffnet `https://business.didit.me/authorize` mit einer S256-PKCE-Challenge. Sie melden sich an (oder registrieren sich) und sehen genau, welche Berechtigungen angefordert werden. Clients sind öffentlich: Der Token-Endpoint akzeptiert kein Client-Secret (`token_endpoint_auth_methods_supported` ist `none`), daher bindet PKCE den Code an den Client. **4. Einwilligung** Sie stimmen zu. Die Console erstellt eine Sitzung für diese Anwendung, gebunden an die von Ihnen genehmigten Scopes, und gibt einen Autorisierungscode zurück, den der Client am `token_endpoint` gegen ein Access-Token und ein Refresh-Token eintauscht. **5. Tools aufrufen** Der Client sendet das Access-Token mit jeder Anfrage. Der MCP validiert es per RFC 7662 Token-Introspektion beim Didit-Auth-Dienst (die Tokens sind opak, keine JWTs), liest Ihre Organisationsberechtigungen aus der Introspektions-Antwort und handelt für die Dauer dieser Anfrage in Ihrem Namen. ### Scopes Die Ressourcen-Metadaten bieten drei Scopes an. Der Zustimmungsbildschirm zeigt die von einem Client angeforderten Scopes in verständlicher Sprache an: | Scope | Berechtigungen | | - | - | | `didit:management` | Ihren Workspace verwalten — `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` und `analytics`. | | `didit:verification` | Verifizierungen durchführen und prüfen — `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` und `analytics`. | | `didit:staff` | Reserviert für Didit-Mitarbeiterkonten. Schaltet für ein reguläres Konto nichts frei, und der Open-Source-Build definiert keine reinen Mitarbeiter-Tools. | Beide Scopes umfassen `analytics`. Das Verwalten von `lists` erfordert `didit:management`; der Zugriff auf `blocklist` erfordert `didit:verification`. Die [Tool-Referenz](https://docs.didit.me/de/integration/mcp/tools.md) führt auf, welchem Scope jedes Tool zugeordnet ist. Die von Ihnen genehmigten Scopes werden im Token mitgeführt und serverseitig erzwungen, sodass eine Anwendung, die nur mit `didit:verification` verbunden ist, auf der Verwaltungsebene abgelehnt wird, selbst wenn Ihre eigene Rolle dies erlauben würde. Der Autorisierungsserver kennt auch die OpenID-Scopes (`openid profile email`); eine Verbindung, die nur diese anfordert, kann feststellen, wer Sie sind, und nichts weiter. Die effektiven Berechtigungen einer Anwendung sind die **Schnittmenge** der genehmigten Scopes und Ihrer Console-Rolle — niemals das weiter gefasste von beiden. Um eine Verifizierungssitzung mit `didit_session_create` zu erstellen, benötigen Sie den Scope `didit:verification` **und** eine Rolle mit `create:sessions` oder `write:sessions`. Die Rolle **Entwickler** enthält `create:sessions`. Die alleinige Genehmigung von `didit:management` erlaubt keine Sitzungserstellung, selbst wenn Ihre Rolle die erforderliche Berechtigung besitzt. ### Rollen und Berechtigungen Das gehostete Token repräsentiert **Sie**, sodass der Agent in einer einzigen Verbindung über **jede Organisation, der Sie angehören**, hinweg arbeiten kann — die anwendungsübergreifenden Tools (`didit_session_search`, `didit_analytics`, `didit_context_get` und die anderen `*_search`-Tools) aggregieren automatisch über alle Organisationen. Ihre **Rolle wird vom Didit-Backend immer erzwungen**, pro Organisation. Jedes Tool ist einem Backend-Berechtigungsstring zugeordnet (zum Beispiel `write:sessions` für `didit_session_update_status`, `delete:sessions` für `didit_session_delete`); die [Tool-Referenz](https://docs.didit.me/de/integration/mcp/tools.md) zeigt dies pro Tool. Der Server prüft diese Berechtigung auch, bevor er die Anfrage sendet, anhand der Berechtigungen, die die Introspektions-Antwort für Ihre Organisation enthält: * Im Modus `enforce` wird ein Tool, dessen Ausführung Ihre Rolle nicht erlaubt, in `tools/list` ausgelassen, und ein Aufruf führt dennoch zu einem `missing_scope`-Fehler, der die Berechtigung benennt (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`). * Im Modus `shadow` (Server-Standard) wird jedes Tool aufgelistet und der Aufruf geht an das Backend weiter, das mit `403` antwortet, wenn der Rolle die Berechtigung fehlt; die Entscheidung wird lediglich im Audit-Log des Servers protokolliert. In beiden Fällen gewährt der MCP niemals mehr, als Ihre Console-Rolle ohnehin erlaubt. Ein `READER` kann auflisten und lesen; ein `OWNER` oder `ADMIN` kann schreiben und löschen. ### Token-Lebensdauer Eine genehmigte Anwendung erhält eine eigene Sitzung, getrennt von der Browser-Sitzung, über die Sie sie genehmigt haben. Access-Tokens sind kurzlebig; der Client erneuert sie geräuschlos mit dem Refresh-Token (`grant_types_supported` umfasst `refresh_token`), und ein Refresh behält die Scopes der Anwendung bei und bleibt an diese Anwendung gebunden. Schlägt ein Refresh fehl (beispielsweise nachdem Sie die Verbindung zur Anwendung getrennt haben), führt der Client beim nächsten Aufruf erneut **Mit Didit anmelden** aus. Das Abmelden von der Konsole meldet verbundene Apps nicht ab, und das Trennen einer App meldet Sie nirgendwo ab. ### Trennen einer App **1. Über die Konsole** Unter **Settings → Authentication → Connected apps** werden alle von Ihnen genehmigten Apps mit ihrem registrierten Namen und den ihnen erteilten Berechtigungen aufgeführt. **Trennen** beendet den Zugriff dieser App sofort: Sowohl ihr Access-Token als auch ihr Refresh-Token verlieren ihre Gültigkeit, und alles andere bleibt unberührt. **2. Über die App (RFC 7009)** Ein Client kann seinen eigenen Zugriff widerrufen, indem er das Token per POST an den `revocation_endpoint` des Autorisierungsservers sendet, der in den Metadaten unter `https://business.didit.me/.well-known/oauth-authorization-server` angegeben ist. Wie von RFC 7009 vorgeschrieben, antwortet ein erfolgreicher Aufruf mit `200`, unabhängig davon, ob das Token noch aktiv war. Die Antwort verrät Ihnen daher nie, ob ein Token gültig war. Ein `503` bedeutet, dass der Widerruf nicht angewendet werden konnte: Behandeln Sie das Token weiterhin als gültig und starten Sie einen Wiederholungsversuch. ```bash theme={null} curl -X POST https://business.didit.me/api/auth/oauth-revoke \ -H "Content-Type: application/json" \ -d '{"token": "", "token_type_hint": "refresh_token", "client_id": ""}' ``` > [!NOTE] > > **Warum kein API-Schlüssel?** Jedes MCP-Tool ruft die benutzerspezifischen Console-Endpoints (`/organization/{org}/application/{app}/…`) auf, die ein Bearer-Token mit rollenbasierten Berechtigungen autorisieren und **`x-api-key` ablehnen**. Ein Anwendungs-API-Schlüssel dient dazu, die [REST-API](https://docs.didit.me/openapi-25.json) direkt aus Ihrem eigenen Backend aufzurufen (z. B. zum Erstellen von Sitzungen) – nicht für dieses MCP. `didit_org_list_api_keys` zeigt Schlüsselmetadaten mit unkenntlich gemachten Werten an; das Tool, das einen rohen API-Schlüssel offenlegt, ist auf dem gehosteten Connector ausgeblendet. *** ## Von jedem Client aus verbinden Jeder Client durchläuft denselben Ablauf; lediglich die Art und Weise, wie Sie ihm die URL übergeben, unterscheidet sich. > [tab] Claude > > Verwenden Sie den Deep-Link, den die Business Console auf ihrer Integrationsseite anzeigt. Er öffnet claude.ai mit vorausgefülltem Dialog **Add custom connector**: > > ```text theme={null} > https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp > ``` > > Bestätigen Sie und schließen Sie dann **Mit Didit anmelden** ab. Claude Desktop verwendet dieselbe URL unter **Settings → Connectors → Add custom connector**. Details finden Sie unter [Claude verbinden](https://docs.didit.me/de/integration/mcp/claude.md). > [tab] Claude Code > > ```bash theme={null} > claude mcp add --transport http didit https://mcp.didit.me/mcp > ``` > > Führen Sie anschließend `/mcp` in Claude Code aus, um die Anmeldung im Browser zu starten. > [tab] Cursor > > `~/.cursor/mcp.json`: > > ```json theme={null} > { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } } > ``` > > Cursor registriert sich selbst und öffnet bei der ersten Verwendung den Browser. > [tab] Generischer Client > > Richten Sie jeden Streamable-HTTP-Client mit OAuth-2.1-Unterstützung auf `https://mcp.didit.me/mcp` aus. Er sollte: > > 1. `POST /mcp` aufrufen, `401` empfangen und `resource_metadata` aus `WWW-Authenticate` auslesen. > 2. `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` abrufen, danach die Metadaten des Autorisierungsservers unter `https://business.didit.me/.well-known/oauth-authorization-server`. > 3. Sich am `registration_endpoint` registrieren, falls er noch keine Client-ID hat. > 4. Den Authorization-Code-Flow mit PKCE (S256) am `authorization_endpoint` durchführen und den Code am `token_endpoint` gegen ein Token eintauschen. > 5. `Authorization: Bearer ` bei jedem `POST /mcp` mitsenden. > > Clients ohne OAuth-Unterstützung können hinter `npx -y mcp-remote@latest https://mcp.didit.me/mcp` betrieben werden, das die Schritte 1–5 für sie übernimmt. *** ## Authentifizierungsfehler ```text theme={null} HTTP 401 WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp" ``` Ein `401` von `/mcp` bedeutet, dass das Token fehlt, abgelaufen ist oder widerrufen wurde – der Client sollte das Token aktualisieren oder **Mit Didit anmelden** erneut ausführen. Ein `403`- oder `missing_scope`-Fehler bei einem *bestimmten* Tool bedeutet in der Regel entweder, dass Ihrer **Rolle** diese Berechtigung fehlt (z. B. ein `READER`, der einen Schreibvorgang versucht), oder dass die Verbindung **ohne den Scope** genehmigt wurde, den dieses Tool benötigt – nicht, dass die gesamte Verbindung unterbrochen ist. Ein erneutes Verbinden und Genehmigen beider Scopes behebt den zweiten Fall; der erste erfordert eine Rollenänderung. Wenn jedes Tool fehlschlägt, überprüfen Sie **Settings → Authentication → Connected apps** in der Konsole: Eine dort getrennte App muss erneut genehmigt werden. *** > [card] [Tools-Referenz](https://docs.didit.me/de/integration/mcp/tools.md) > > Was jedes Tool tut, sein Scope und seine Rollenberechtigung. > [card] [Erweitert](https://docs.didit.me/de/integration/mcp/advanced.md) > > Rollen, anwendungsübergreifendes Verhalten und Self-Hosting. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.