Skip to main content
Using our API via a dedicated deployment? Just replace api.langdock.com with your deployment’s base URL: <deployment-url>/api/public
Configures the authentication method for an integration. This sets how users connect to the external service — via API key, OAuth, service account, or no authentication.
Changing the authType deletes all existing user connections to this integration. Users will need to reconnect.

Required Scopes

This endpoint requires the INTEGRATION_API scope.

Path Parameters

ParameterTypeRequiredDescription
integrationIdstringYesUUID of the integration

Request Body

ParameterTypeRequiredDescription
authTypestringYesAuthentication method (see Auth Types below)
authFieldsarrayNoFields users fill in when connecting (see Auth Field Schema)
authTestCodestringNoJavaScript code to validate credentials (max 1,000 characters)
oauthClientobjectNoOAuth configuration (only for OAUTH / OAUTH_DCR auth types)

Auth Types

TypeDescription
NONENo authentication required
API_KEYUsers provide credentials via custom auth fields
SERVICE_ACCOUNTService-level credentials via auth fields
OAUTHOAuth 2.0 flow with authorization code
OAUTH_DCROAuth 2.0 with Dynamic Client Registration

Auth Field Schema

Each auth field defines a credential input that users fill in when connecting to the integration.
PropertyTypeRequiredDescription
slugstringYesUnique identifier for the field (max 100 characters)
labelstringYesDisplay label (max 100 characters)
typestringYesInput type (see Field Types below)
descriptionstringNoHelp text (max 500 characters, default: "")
placeholderstringNoPlaceholder text (max 200 characters)
requiredbooleanNoWhether the field is required (default: false)
The slug must be unique within the integration. The field id is auto-generated — do not include it in the request.

Field Types

TypeDescription
TEXTSingle-line text input
MULTI_LINE_TEXTMulti-line text input
PASSWORDMasked password input
NUMBERNumeric input
EMBEDDING_MODELEmbedding model selector

OAuth Client Schema

Only relevant when authType is OAUTH or OAUTH_DCR.
PropertyTypeRequiredDescription
scopesstringNoSpace-separated OAuth scopes (max 2,000 characters)
authUrlstringNoAuthorization endpoint URL
tokenUrlstringNoToken endpoint URL
clientIdstringNoOAuth client ID (max 500 characters)
clientSecretstringNoOAuth client secret (max 500 characters, write-only)
labelstringNoDisplay label for the connect button (max 100 characters)
authorizationCodestringNoCustom authorization code (max 1,000 characters)
accessTokenCodestringNoCustom access token code (max 1,000 characters)
refreshTokenCodestringNoCustom refresh token code (max 1,000 characters)
OAuth credentials (clientId, clientSecret, authUrl, tokenUrl) are write-only — they are never returned in API responses.

Example: API Key Authentication

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");

Response Format

Success Response (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;
  };
}

Behavior

  • Auth fields are fully replaced on every call — the entire array is deleted and recreated.
  • Changing authType deletes all existing user connections and any previous OAuth client configuration.
  • Setting authType to NONE, API_KEY, or SERVICE_ACCOUNT deletes any existing OAuth client.
  • OAuth credentials (clientId, clientSecret) are encrypted before storage.

Error Handling

Status CodeDescription
400Invalid request body or integration ID
401Invalid or missing API key
403No access to this integration
404Integration not found
429Rate limit exceeded
500Internal server error
Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.