Zum Hauptinhalt springen
Nutzt du unsere API über ein Dedicated Deployment? Ersetze einfach api.langdock.com mit der Basis-URL deines Deployments: <deployment-url>/api/public
Konfiguriert die Authentifizierungsmethode für eine Integration. Damit legst du fest, wie sich Nutzer mit dem externen Service verbinden — per API Key, OAuth, Service Account oder ohne Authentifizierung.
Das Ändern des authType löscht alle bestehenden Nutzerverbindungen zu dieser Integration. Nutzer müssen sich erneut verbinden.

Erforderliche Scopes

Dieser Endpoint erfordert den INTEGRATION_API Scope.

Pfad-Parameter

ParameterTypErforderlichBeschreibung
integrationIdstringJaUUID der Integration

Request Body

ParameterTypErforderlichBeschreibung
authTypestringJaAuthentifizierungsmethode (siehe Auth-Typen unten)
authFieldsarrayNeinFelder, die Nutzer beim Verbinden ausfüllen (siehe Auth-Feld-Schema)
authTestCodestringNeinJavaScript-Code zur Validierung der Zugangsdaten (max. 1.000 Zeichen)
oauthClientobjectNeinOAuth-Konfiguration (nur für OAUTH / OAUTH_DCR Auth-Typen)

Auth-Typen

TypBeschreibung
NONEKeine Authentifizierung erforderlich
API_KEYNutzer geben Zugangsdaten über benutzerdefinierte Auth-Felder ein
SERVICE_ACCOUNTService-Level-Zugangsdaten über Auth-Felder
OAUTHOAuth 2.0 Flow mit Authorization Code
OAUTH_DCROAuth 2.0 mit Dynamic Client Registration

Auth-Feld-Schema

Jedes Auth-Feld definiert ein Eingabefeld, das Nutzer beim Verbinden mit der Integration ausfüllen.
EigenschaftTypErforderlichBeschreibung
slugstringJaEindeutiger Bezeichner für das Feld (max. 100 Zeichen)
labelstringJaAnzeigebezeichnung (max. 100 Zeichen)
typestringJaEingabetyp (siehe Feldtypen unten)
descriptionstringNeinHilfetext (max. 500 Zeichen, Standard: "")
placeholderstringNeinPlatzhaltertext (max. 200 Zeichen)
requiredbooleanNeinOb das Feld erforderlich ist (Standard: false)
Der slug muss innerhalb der Integration eindeutig sein. Die Feld-id wird automatisch generiert — füge sie nicht in den Request ein.

Feldtypen

TypBeschreibung
TEXTEinzeilige Texteingabe
MULTI_LINE_TEXTMehrzeilige Texteingabe
PASSWORDMaskierte Passworteingabe
NUMBERNumerische Eingabe
EMBEDDING_MODELEmbedding-Modell-Auswahl

OAuth-Client-Schema

Nur relevant, wenn authType OAUTH oder OAUTH_DCR ist.
EigenschaftTypErforderlichBeschreibung
scopesstringNeinDurch Leerzeichen getrennte OAuth-Scopes (max. 2.000 Zeichen)
authUrlstringNeinAuthorization-Endpoint-URL
tokenUrlstringNeinToken-Endpoint-URL
clientIdstringNeinOAuth Client ID (max. 500 Zeichen)
clientSecretstringNeinOAuth Client Secret (max. 500 Zeichen, nur schreibbar)
labelstringNeinAnzeigebezeichnung für den Verbinden-Button (max. 100 Zeichen)
authorizationCodestringNeinBenutzerdefinierter Authorization-Code (max. 1.000 Zeichen)
accessTokenCodestringNeinBenutzerdefinierter Access-Token-Code (max. 1.000 Zeichen)
refreshTokenCodestringNeinBenutzerdefinierter Refresh-Token-Code (max. 1.000 Zeichen)
OAuth-Zugangsdaten (clientId, clientSecret, authUrl, tokenUrl) sind nur schreibbar — sie werden nie in API-Antworten zurückgegeben.

Beispiel: API-Key-Authentifizierung

const axios = require("axios");

async function configureAuth(integrationId) {
  const response = await axios.patch(
    `https://api.langdock.com/integrations/v1/${integrationId}/auth`,
    {
      authType: "API_KEY",
      authFields: [
        {
          slug: "api_key",
          label: "API Key",
          type: "PASSWORD",
          description: "Your API key from the service dashboard",
          placeholder: "sk-...",
          required: true
        },
        {
          slug: "base_url",
          label: "Base URL",
          type: "TEXT",
          description: "API base URL",
          placeholder: "https://api.example.com",
          required: true
        }
      ],
      authTestCode: `
        const response = await fetch(secrets.base_url + '/me', {
          headers: { 'Authorization': 'Bearer ' + secrets.api_key }
        });
        if (!response.ok) throw new Error('Invalid credentials');
        return { success: true };
      `
    },
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
      }
    }
  );

  console.log("Auth configured:", response.data.integration);
}

configureAuth("550e8400-e29b-41d4-a716-446655440000");

Antwortformat

Erfolgreiche Antwort (200 OK)

{
  integration: {
    id: string;
    authType: string;
    authTestCode: string | null;
    authFields: Array<{
      slug: string;
      label: string;
      type: string;
      description: string;
      placeholder: string | null;
      required: boolean;
    }>;
    oauthClient: {
      scopes: string | null;
      label: string | null;
      authorizationCode: string;
      accessTokenCode: string;
      refreshTokenCode: string;
    } | null;
  };
}

Verhalten

  • Auth-Felder werden bei jedem Aufruf komplett ersetzt — das gesamte Array wird gelöscht und neu erstellt.
  • Das Ändern des authType löscht alle bestehenden Nutzerverbindungen und jede vorherige OAuth-Client-Konfiguration.
  • Das Setzen von authType auf NONE, API_KEY oder SERVICE_ACCOUNT löscht jeden vorhandenen OAuth-Client.
  • OAuth-Zugangsdaten (clientId, clientSecret) werden vor der Speicherung verschlüsselt.

Fehlerbehandlung

Status CodeBeschreibung
400Ungültiger Request Body oder Integrations-ID
401Ungültiger oder fehlender API-Schlüssel
403Kein Zugriff auf diese Integration
404Integration nicht gefunden
429Rate Limit überschritten
500Interner Serverfehler
Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen und die Sicherheit deiner Anwendungen zu gewährleisten. Weitere Informationen findest du in unserem Guide zu Best Practices für API-Schlüssel.