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
| Parameter | Typ | Erforderlich | Beschreibung |
|---|
integrationId | string | Ja | UUID der Integration |
Request Body
| Parameter | Typ | Erforderlich | Beschreibung |
|---|
authType | string | Ja | Authentifizierungsmethode (siehe Auth-Typen unten) |
authFields | array | Nein | Felder, die Nutzer beim Verbinden ausfüllen (siehe Auth-Feld-Schema) |
authTestCode | string | Nein | JavaScript-Code zur Validierung der Zugangsdaten (max. 1.000 Zeichen) |
oauthClient | object | Nein | OAuth-Konfiguration (nur für OAUTH / OAUTH_DCR Auth-Typen) |
Auth-Typen
| Typ | Beschreibung |
|---|
NONE | Keine Authentifizierung erforderlich |
API_KEY | Nutzer geben Zugangsdaten über benutzerdefinierte Auth-Felder ein |
SERVICE_ACCOUNT | Service-Level-Zugangsdaten über Auth-Felder |
OAUTH | OAuth 2.0 Flow mit Authorization Code |
OAUTH_DCR | OAuth 2.0 mit Dynamic Client Registration |
Auth-Feld-Schema
Jedes Auth-Feld definiert ein Eingabefeld, das Nutzer beim Verbinden mit der Integration ausfüllen.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|
slug | string | Ja | Eindeutiger Bezeichner für das Feld (max. 100 Zeichen) |
label | string | Ja | Anzeigebezeichnung (max. 100 Zeichen) |
type | string | Ja | Eingabetyp (siehe Feldtypen unten) |
description | string | Nein | Hilfetext (max. 500 Zeichen, Standard: "") |
placeholder | string | Nein | Platzhaltertext (max. 200 Zeichen) |
required | boolean | Nein | Ob 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
| Typ | Beschreibung |
|---|
TEXT | Einzeilige Texteingabe |
MULTI_LINE_TEXT | Mehrzeilige Texteingabe |
PASSWORD | Maskierte Passworteingabe |
NUMBER | Numerische Eingabe |
EMBEDDING_MODEL | Embedding-Modell-Auswahl |
OAuth-Client-Schema
Nur relevant, wenn authType OAUTH oder OAUTH_DCR ist.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|
scopes | string | Nein | Durch Leerzeichen getrennte OAuth-Scopes (max. 2.000 Zeichen) |
authUrl | string | Nein | Authorization-Endpoint-URL |
tokenUrl | string | Nein | Token-Endpoint-URL |
clientId | string | Nein | OAuth Client ID (max. 500 Zeichen) |
clientSecret | string | Nein | OAuth Client Secret (max. 500 Zeichen, nur schreibbar) |
label | string | Nein | Anzeigebezeichnung für den Verbinden-Button (max. 100 Zeichen) |
authorizationCode | string | Nein | Benutzerdefinierter Authorization-Code (max. 1.000 Zeichen) |
accessTokenCode | string | Nein | Benutzerdefinierter Access-Token-Code (max. 1.000 Zeichen) |
refreshTokenCode | string | Nein | Benutzerdefinierter 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");
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 Code | Beschreibung |
|---|
| 400 | Ungültiger Request Body oder Integrations-ID |
| 401 | Ungültiger oder fehlender API-Schlüssel |
| 403 | Kein Zugriff auf diese Integration |
| 404 | Integration nicht gefunden |
| 429 | Rate Limit überschritten |
| 500 | Interner 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.