💻Leitfaden zur externen API-Integration

Umfassende Anleitung zur Integration Ihrer externen REST- oder GraphQL-APIs mit unserer Plattform.

Was Sie benötigen

• Einen REST- oder GraphQL-API-Dienst

• OpenAPI 3.0+-Spezifikation (JSON- oder YAML-Format)

• Einen sicheren Authentifizierungsmechanismus

• HTTPS-fähige Endpunkte

• Tenant-Administrator-Zugang für die Einrichtung

---

Erste Schritte

Voraussetzungen

Wichtig: Sie müssen Tenant-Administrator sein, um externe Dienste hinzuzufügen.

Schritt 1: API-Spezifikation vorbereiten

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 wählen

Wählen Sie die passende Authentifizierungsmethode für Ihren Anwendungsfall:

• Fester API-Token: Für die Dienst-zu-Dienst-Authentifizierung

• Benutzer-Token (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 zugängliche Endpunkt-URL

Hinweis: Direkte Datei-Uploads werden derzeit nicht unterstützt. Ihre OpenAPI-Spezifikation muss über eine öffentliche URL erreichbar sein.

Beispiel einer OpenAPI 3.1-Struktur:

YAMLFullscreenCopy codeopenapi: 3.1.0  
info:  
  title: Your API Name  
  version: 1.0.0  
  description: API description  
servers:  
    - url: https://api.yourcompany.com/v1  
    description: Production server  
paths:  
  /resource:  
    get:  
      summary: Get resource  
      operationId: getResource  
      responses:  
        '200':  
          description: Successful response  
          content:  
            application/json:  
              schema:  
                type: object  
components:  
  securitySchemes:  
    ApiKeyAuth:  
      type: apiKey  
      in: header  
      name: X-API-Key  

Pflichtanforderungen:

• Gültige Konformität mit OpenAPI 3.0+-Standards

• Vollständige Endpunktdefinitionen mit operationId-Feldern

• Klare Sicherheitsschemadefinitionen

• Umfassende Endpunkt- und Parameterbeschreibungen

• Beispielantworten, wo anwendbar

GraphQL Schema

Format: SDL (Schema Definition Language)

GraphQLFullscreenCopy codetype Query {  
  getResource(id: ID!): Resource  
}

type Resource {  
  id: ID!  
  name: String!  
  description: String  
}  

---

Authentifizierungsmethoden

MVP-Hinweis: Derzeit werden nur API Key und Basic Authentication unterstützt. Benutzer-Token (Delegierter Zugriff) ist noch nicht verfügbar.

Option 1: API Key

Am besten geeignet für: Dienst-zu-Dienst-Authentifizierung ohne Benutzerkontext

Funktionsweise:

1. Sie stellen einen langlebigen API-Key bereit

2. Wir speichern ihn verschlüsselt in unserem System (mandantenbasierte Verschlüsselung)

3. Wir fügen ihn bei jeder Anfrage in den Authorization-Header ein

Ihre Anforderungen:

• Einen sicheren, langlebigen API-Key generieren

• Sicherstellen, dass der Key über geeignete Berechtigungen verfügt

• Einen Key-Rotationsmechanismus bereitstellen

• Die API-Key-Nutzung überwachen

Option 2: Basic Authentication

Am besten geeignet für: APIs, die sich über Benutzername und Passwort authentifizieren

Funktionsweise:

1. Sie stellen einen Benutzernamen und ein Passwort bereit

2. Wir speichern die Anmeldeinformationen verschlüsselt in unserem System (mandantenbasierte Verschlüsselung)

3. Wir kodieren sie als Base64-Authorization: Basic <credentials>-Header bei jeder Anfrage

Ihre Anforderungen:

• Gültige Benutzername- und Passwort-Anmeldeinformationen bereitstellen

• Sicherstellen, dass die Anmeldeinformationen über geeignete Zugriffsberechtigungen verfügen

• Wenn möglich, eine Anmeldeinformations-Rotation implementieren

• Die Authentifizierungsnutzung überwachen

---

Einrichtungsanleitung

Schritt 1: Zu Custom Integrations navigieren

1. Melden Sie sich in Ihrem Tenant-Admin-Konto an

2. Gehen Sie zu Einstellungen → Integrationen → Custom Integrations (oder Connectors)

3. Klicken Sie auf Neue Integration hinzufügen

Schritt 2: Integrationstyp wählen

Wählen Sie eine der folgenden Optionen:

• 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
Base URL	API-Basisendpunkt	Ja
OpenAPI Spec	URL zur JSON/YAML-Spezifikationsdatei	Ja
Authorization Method	API Key oder Basic Authentication	Ja
API Key	Ihr API-Key (bei API Key Auth)	Bedingt
Username	Ihr Benutzername (bei Basic Authentication)	Bedingt
Password	Ihr Passwort (bei Basic Authentication)	Bedingt
Additional Headers	Benutzerdefinierte Header (Schlüssel-Wert-Paare)	Nein
Endpoint Filtering	Konfigurieren, welche Endpunkte freigegeben werden	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
Base URL	MCP-Server-Endpunkt	Ja
Transport	SSE oder HTTP	Ja
Authorization Method	API Key oder Basic Authentication	Ja
API Key	Ihr API-Key (bei API Key Auth)	Bedingt
Username	Ihr Benutzername (bei Basic Authentication)	Bedingt
Password	Ihr Passwort (bei Basic Authentication)	Bedingt
Resource Filter	Kommagetrennte Ressourcen-URIs (optional)	Empfohlen
Tool Filter	Kommagetrennte Tool-Namen (optional)	Empfohlen
Max Tools	Maximale Anzahl an Tools	Nein
Max Resources	Maximale Anzahl an Ressourcen	Nein

Schritt 4: Konfiguration validieren

Unser System führt automatisch folgende Prüfungen durch:

• Scannen und Validieren Ihrer OpenAPI-Spezifikation (für APIs)

• Verbindungstest zu Ihrem Server

• Überprüfung der Authentifizierungsdaten

• Auflistung verfügbarer Tools/Ressourcen (für MCP)

---

Sicherheitsrichtlinien

Universelle Anforderungen (alle Authentifizierungsmethoden)

Erforderliche Sicherheitsmaßnahmen:

• Nur HTTPS: Alle Endpunkte müssen HTTPS verwenden

• Eingabevalidierung: Alle Eingaben vor der Verarbeitung bereinigen

• Ausgabefilterung: Sensible Daten aus Antworten entfernen

• Zugangskontrolle: Rollenbasierte Zugangskontrolle (RBAC) implementieren

• Audit-Protokollierung: Alle API-Zugriffe mit Benutzerkontext protokollieren

• Datenverschlüsselung: Sensible Daten im Ruhezustand und bei der Übertragung verschlüsseln

• Rate Limiting: Missbrauch durch Anfragedrosselung verhindern

Empfohlene zusätzliche Sicherheitsmaßnahmen:

• IP-Whitelisting (kontaktieren Sie uns für die Egress-IP)

• API-Gateways für zentralisierte Sicherheit

• DDoS-Schutz

• Regelmäßige Sicherheitsprüfungen

• Notfallplan für Sicherheitsvorfälle

---

Validierung & Testing

Validierungstools

Validieren Sie Ihre Spezifikation vor der Einreichung mit:

1. Swagger Editor — Interaktive Validierung

2. OpenAPI Validator — Automatisierte Prüfungen

Test-Checkliste

• OpenAPI-Spezifikation besteht die Validierung

• Alle Endpunkte haben korrekte operationId-Felder

• Sicherheitsschemata sind korrekt definiert

• Der Authentifizierungsablauf funktioniert wie erwartet

• Rate Limiting ist ordnungsgemäß konfiguriert

• Fehlerantworten sind gut dokumentiert

---

Agent-Zuweisung

Schritt 5: Einem Agent zuweisen

Nach erfolgreicher Konfiguration Ihrer Integration weisen Sie diese Agents zu:

1. Navigieren Sie zu Agent-Einstellungen im Admin-Panel oder in der Agent-Auswahl in einem Data Room

2. Wählen Sie den Agent aus, den Sie konfigurieren möchten

3. Wählen Sie unter External APIs Ihre neu erstellte Integration aus

4. Speichern Sie die Agent-Konfiguration

MCP-Server-Hinweise

Best Practices für Tool-Design:

• Die Anzahl der freigegebenen Tools begrenzen (empfohlen: maximal 10–20)

• Klare, handlungsorientierte Tool-Namen verwenden

• Umfassende Eingabe-Schemas bereitstellen

• Fehler mit beschreibenden Meldungen behandeln

Ressourcenverwaltung:

• Explizite Ressourcen-URIs definieren

• Geeignete MIME-Typen verwenden

• Effiziente Caching-Strategien implementieren

Performance:

• Timeout-Behandlung implementieren

• Paginierung für große Datensätze verwenden

• Häufig abgerufene Ressourcen cachen

---

Nächste Schritte

1. API-Spezifikation vorbereiten gemäß den oben genannten Anforderungen

2. Authentifizierungsmethode wählen und implementieren (API Key oder Basic Authentication)

3. Spezifikation validieren mit den empfohlenen Tools

4. Integration testen in Ihrer Entwicklungsumgebung

5. Tenant-Admin-Konto aufrufen um die Integration zu konfigurieren

6. Einrichtungsanleitung befolgen um Ihren Dienst hinzuzufügen

7. Integration Agents zuweisen nach Bedarf