Leitfaden zur Integration externer APIs

Umfassende Anweisungen zur Integration Ihrer externen REST- oder GraphQL-APIs in unsere Plattform.

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: https://agentic.theblockbrain.ai/docs#description/introduction

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:

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)

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 <credentials> 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 — Interaktive Validierung

2. 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