# Leitfaden zur Integration externer APIs {% hint style="info" %} ## Wählen Sie den Endpunkt für Bots oder Agents Beachten Sie, dass **getrennte API-Endpunkte** für Bots und Agents vorhanden sind. Für die **Agents-API** verwenden Sie dies: {% endhint %} #### **Was Sie benötigen** * Einen REST- oder GraphQL-API-Dienst * OpenAPI-3.0+-Spezifikation (JSON- oder YAML-Format) * Sicherer Authentifizierungsmechanismus * HTTPS-fähige Endpunkte * **Zugriff als Tenant-Administrator** für die Einrichtung ### **Erste Schritte** #### **Voraussetzungen** **Wichtig**: Sie müssen ein **Tenant-Administrator** sein, um externe Dienste hinzuzufügen. #### **Schritt 1: Bereiten Sie Ihre API-Spezifikation vor** Ihre API muss in einem der unterstützten Spezifikationsformate dokumentiert sein: * **OpenAPI 3.0+** (Empfohlen – JSON- oder YAML-Format) * **GraphQL-Schema** (SDL-Format) #### **Schritt 2: Authentifizierungsmethode auswählen** Wählen Sie die geeignete Authentifizierungsmethode basierend auf Ihrem Anwendungsfall: * **Fester API-Token**: Für die Service-zu-Service-Authentifizierung * **Benutzertoken (delegierter Zugriff)**: Für benutzerspezifischen Datenzugriff #### **Schritt 3: Sicherheit konfigurieren** Stellen Sie sicher, dass Ihre API geeignete Sicherheitsmaßnahmen implementiert, einschließlich HTTPS, Eingabevalidierung und Zugriffskontrollen. ### **Anforderungen an die API-Spezifikation** #### **OpenAPI-Spezifikation (empfohlen)** **Erforderliche Elemente:** * **Format**: JSON oder YAML * **Version**: OpenAPI 3.0+ (3.1 empfohlen) * **Bereitstellung**: Öffentlich verfügbarer Endpunkt-URL > **Hinweis:** Direkte Datei-Uploads werden derzeit nicht unterstützt. Ihre OpenAPI-Spezifikation muss über eine öffentliche URL zugänglich sein. **Beispiel für eine OpenAPI-3.1-Struktur:** ```yaml YAMLFullscreenCopy codeopenapi: 3.1.0 info: title: Ihr API-Name version: 1.0.0 description: API-Beschreibung servers: - url: https://api.yourcompany.com/v1 description: Produktionsserver paths: /resource: get: summary: Ressource abrufen operationId: getResource responses: '200': description: Erfolgreiche Antwort content: application/json: schema: type: object components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ``` **Muss-Anforderungen:** * Einhaltung der gültigen OpenAPI-3.0+-Standards * Vollständige Endpunktdefinitionen mit `operationId` Feldern * Klare Definitionen des Sicherheitsschemas * Umfassende Beschreibungen der Endpunkte und Parameter * Beispielantworten, wo anwendbar #### **GraphQL-Schema** **Format: SDL (Schema Definition Language)** ```graphql GraphQLFullscreenCopy codetype Query { getResource(id: ID!): Resource } type Resource { id: ID! name: String! description: String } ``` *** ### **Authentifizierungsmethoden** > **Hinweis zum MVP:** Derzeit werden nur **API-Key** und **Basic Authentication** unterstützt. User Token (delegierter Zugriff) ist noch nicht verfügbar. #### **Option 1: API-Key** **Am besten für:** Service-zu-Service-Authentifizierung ohne Benutzerkontext **So funktioniert es:** 1. Sie stellen einen lang gültigen API-Schlüssel bereit 2. Wir speichern ihn verschlüsselt in unserem System (mandantenbasierte Verschlüsselung) 3. Wir fügen ihn in den `Authorization` Header für jede Anfrage ein **Ihre Anforderungen:** * Erstellen Sie einen sicheren, lang gültigen API-Schlüssel * Stellen Sie sicher, dass der Schlüssel über die entsprechenden Berechtigungen verfügt * Stellen Sie einen Mechanismus zur Schlüsselrotation bereit * Überwachen Sie die Nutzung des API-Schlüssels #### **Option 2: Basic Authentication** **Am besten für:** APIs, die sich über Benutzername-und-Passwort-Zugangsdaten authentifizieren **So funktioniert es:** 1. Sie stellen einen Benutzernamen und ein Passwort bereit 2. Wir speichern die Zugangsdaten verschlüsselt in unserem System (mandantenbasierte Verschlüsselung) 3. Wir kodieren sie als Base64 `Authorization: Basic ` Header bei jeder Anfrage ein **Ihre Anforderungen:** * Stellen Sie gültige Benutzername-und-Passwort-Zugangsdaten bereit * Stellen Sie sicher, dass die Zugangsdaten über die entsprechenden Zugriffsberechtigungen verfügen * Implementieren Sie nach Möglichkeit eine Rotation der Zugangsdaten * Überwachen Sie die Authentifizierungsnutzung *** ### **Einrichtungsanweisungen** #### **Schritt 1: Zu benutzerdefinierten Integrationen navigieren** 1. **Melden Sie sich** bei Ihrem Tenant-Admin-Konto an 2. Gehen Sie zu **Einstellungen** → **Integrationen** → **Benutzerdefinierte Integrationen** (oder **Connectors**) 3. Klicken Sie auf **Neue Integration hinzufügen** #### **Schritt 2: Integrationstyp auswählen** Wählen Sie eine der folgenden Optionen aus: * **API-Integration** (für REST-/GraphQL-APIs) * **MCP-Server** (für Model-Context-Protocol-Server) #### **Schritt 3: Integrationseinstellungen konfigurieren** **Für API-Integration** | Feld | Beschreibung | Erforderlich | | ------------------------- | ------------------------------------------------------------------- | ------------ | | **Name** | Anzeigename der Integration | Ja | | **Basis-URL** | Basis-Endpunkt der API | Ja | | **OpenAPI-Spezifikation** | URL zur JSON-/YAML-Spezifikationsdatei | Ja | | **Autorisierungsmethode** | API-Key oder Basic Authentication | Ja | | **API-Key** | Ihr API-Schlüssel (bei API-Key-Authentifizierung) | Bedingt | | **Benutzername** | Ihr Benutzername (bei Basic Authentication) | Bedingt | | **Passwort** | Ihr Passwort (bei Basic Authentication) | Bedingt | | **Zusätzliche Header** | Benutzerdefinierte Header (Schlüssel-Wert-Paare) | Nein | | **Endpunktfilterung** | Konfigurieren Sie, welche Endpunkte verfügbar gemacht werden sollen | Empfohlen | > **Hinweis:** Der direkte Datei-Upload für die OpenAPI-Spezifikation wird derzeit nicht unterstützt. Geben Sie stattdessen eine öffentlich zugängliche URL an. **Für MCP-Server** | Feld | Beschreibung | Erforderlich | | ------------------------- | ------------------------------------------------- | ------------ | | **Name** | Anzeigename der Integration | Ja | | **Basis-URL** | MCP-Server-Endpunkt | Ja | | **Transport** | SSE oder HTTP | Ja | | **Autorisierungsmethode** | API-Key oder Basic Authentication | Ja | | **API-Key** | Ihr API-Schlüssel (bei API-Key-Authentifizierung) | Bedingt | | **Benutzername** | Ihr Benutzername (bei Basic Authentication) | Bedingt | | **Passwort** | Ihr Passwort (bei Basic Authentication) | Bedingt | | **Ressourcenfilter** | Kommagetrennte Ressourcen-URIs (optional) | Empfohlen | | **Tool-Filter** | Kommagetrennte Tool-Namen (optional) | Empfohlen | | **Max. Tools** | Maximale Anzahl an Tools | Nein | | **Max. Ressourcen** | Maximale Anzahl an Ressourcen | Nein | #### **Schritt 4: Konfiguration validieren** Unser System wird automatisch: * Ihre OpenAPI-Spezifikation scannen und validieren (für APIs) * Die Verbindung zu Ihrem Server testen * Authentifizierungsdaten überprüfen * Verfügbare Tools/Ressourcen auflisten (für MCP) *** ### **Sicherheitsrichtlinien** #### **Allgemeine Anforderungen (alle Authentifizierungsmethoden)** **Erforderliche Sicherheitsmaßnahmen:** * **Nur HTTPS**: Alle Endpunkte müssen HTTPS verwenden * **Eingabevalidierung**: Säubern Sie alle Eingaben vor der Verarbeitung * **Ausgabefilterung**: Entfernen Sie sensible Daten aus Antworten * **Zugriffskontrolle**: Implementieren Sie eine rollenbasierte Zugriffskontrolle (RBAC) * **Audit-Logging**: Protokollieren Sie den gesamten API-Zugriff mit Benutzerkontext * **Datenverschlüsselung**: Verschlüsseln Sie sensible Daten im Ruhezustand und während der Übertragung * **Ratenbegrenzung**: Verhindern Sie Missbrauch durch Drosselung von Anfragen #### **Empfohlene zusätzliche Sicherheitsmaßnahmen:** * IP-Whitelisting (kontaktieren Sie uns für die Egress-IP) * API-Gateways für zentrale Sicherheit * DDoS-Schutz * Regelmäßige Sicherheitsaudits * Incident-Response-Plan *** ### **Validierung & Testen** #### **Validierungstools** Bevor Sie Ihre Spezifikation einreichen, validieren Sie sie mit: 1. [**Swagger Editor**](https://editor.swagger.io/) — Interaktive Validierung 2. [**OpenAPI Validator**](https://github.com/openapi-library/openapi-validator) — Automatisierte Prüfungen #### **Test-Checkliste** * OpenAPI-Spezifikation besteht die Validierung * Alle Endpunkte haben korrekte `operationId` Feldern * Sicherheits-Schemata sind korrekt definiert * Der Authentifizierungsfluss funktioniert wie erwartet * Die Ratenbegrenzung ist korrekt konfiguriert * Fehlerantworten sind gut dokumentiert *** ### **Agentenzuweisung** #### **Schritt 5: Agent zuweisen** Nachdem Sie Ihre Integration erfolgreich konfiguriert haben, weisen Sie sie Agents zu: 1. Navigieren Sie zu **Agenteneinstellungen** im Admin-Panel oder in der Agentenauswahl in einem Data Room 2. Wählen Sie den Agenten aus, den Sie konfigurieren möchten 3. Unter **Externe APIs**, wählen Sie Ihre neu erstellte Integration aus 4. **Speichern** Agentenkonfiguration #### **Überlegungen zum MCP-Server** **Best Practices für das Tool-Design:** * Begrenzen Sie die Anzahl der bereitgestellten Tools (empfohlen: **maximal 10–20**) * Verwenden Sie klare, handlungsorientierte Tool-Namen * Stellen Sie umfassende Eingabeschemata bereit * Behandeln Sie Fehler mit aussagekräftigen Meldungen elegant **Ressourcenverwaltung:** * Definieren Sie explizite Ressourcen-URIs * Verwenden Sie geeignete MIME-Typen * Implementieren Sie effiziente Caching-Strategien **Leistung:** * Implementieren Sie eine Time-out-Behandlung * Verwenden Sie Paginierung für große Datensätze * Zwischenspeichern häufig abgerufener Ressourcen *** ### **Nächste Schritte** 1. **Bereiten Sie Ihre API-Spezifikation vor** gemäß den oben genannten Anforderungen 2. **Wählen und implementieren Sie Ihre Authentifizierungsmethode** (API-Key oder Basic Authentication) 3. **Validieren Sie Ihre Spezifikation** mit den empfohlenen Tools 4. **Testen Sie die Integration** in Ihrer Entwicklungsumgebung 5. **Greifen Sie auf Ihr Tenant-Admin-Konto zu** um die Integration zu konfigurieren 6. **Befolgen Sie die Einrichtungsanweisungen** um Ihren Dienst hinzuzufügen 7. **Weisen Sie die Integration Agents zu** bei Bedarf --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.en.theblockbrain.ai/de/fur-administratoren/leitfaden-zur-integration-externer-apis.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.