Update Auth Configuration

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.

Before You Start

Changing authType: Changing the authType deletes all existing user connections to this integration. Users will need to reconnect.

Base URL

https://api.langdock.com/integrations/v1/{integrationId}/auth

Dedicated deploymentsReplace api.langdock.com with <your-deployment-url>/api/public in all requests.

Required Scopes

This endpoint requires the INTEGRATION_API scope.

Parameters

Path Parameters

Parameter	Type	Required	Description
`integrationId`	string	Yes	UUID of the integration

Request Body

Parameter	Type	Required	Description
`authType`	string	Yes	Authentication method (see Auth Types below)
`authFields`	array	No	Fields users fill in when connecting (see Auth Field Schema)
`authTestCode`	string	No	JavaScript code to validate credentials (max 1,000 characters)
`oauthClient`	object	No	OAuth configuration (only for the `OAUTH` auth type)

Auth Types

Type	Description
`NONE`	No authentication required
`API_KEY`	Users provide credentials via custom auth fields
`OAUTH`	OAuth 2.0 flow with authorization code

OAUTH_DCR and OAUTH_CIMD are used by MCP integrations and can’t be set through this endpoint. Requests with either value return 400.

Auth Field Schema

Each auth field defines a credential input that users fill in when connecting to the integration.

Property	Type	Required	Description
`slug`	string	Yes	Unique identifier for the field (max 100 characters)
`label`	string	Yes	Display label (max 100 characters)
`type`	string	Yes	Input type (see Field Types below)
`description`	string	No	Help text (max 500 characters, default: `""`)
`placeholder`	string	No	Placeholder text (max 200 characters)
`required`	boolean	No	Whether 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

Type	Description
`TEXT`	Single-line text input
`MULTI_LINE_TEXT`	Multi-line text input
`PASSWORD`	Masked password input
`NUMBER`	Numeric input
`EMBEDDING_MODEL`	Embedding model selector

OAuth Client Schema

Only relevant when authType is OAUTH. Your authorizationCode and accessTokenCode scripts receive PKCE values. See Authorization Code with PKCE.

Property	Type	Required	Description
`scopes`	string	No	Space-separated OAuth scopes (max 2,000 characters)
`authUrl`	string	No	Authorization endpoint URL
`tokenUrl`	string	No	Token endpoint URL
`clientId`	string	No	OAuth client ID (max 500 characters)
`clientSecret`	string	No	OAuth client secret (max 500 characters, write-only)
`authFieldValues`	object	No	Default values for auth fields, keyed by `slug` (`OAUTH` only, keys max 100 characters, values max 2,000 characters)
`label`	string	No	Display label for the connect button (max 100 characters)
`authorizationCode`	string	No	Custom authorization code (max 1,000 characters)
`accessTokenCode`	string	No	Custom access token code (max 1,000 characters)
`refreshTokenCode`	string	No	Custom 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 ld.request({
          method: "GET",
          url: data.auth.base_url + "/me",
          headers: { Authorization: "Bearer " + data.auth.api_key }
        });
        if (response.status < 200 || response.status >= 300) {
          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;
      authFieldValues?: { [slug: string]: 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.
authFieldValues replaces stored defaults on OAUTH when you send it. Omit the property to keep the stored values. Unknown or empty keys are dropped.
PASSWORD values are encrypted and returned as ***********. Send that mask to keep the stored secret. Other values return as text. The response omits authFieldValues when nothing is stored.

Error Handling

Status Code	Description
400	Invalid request body or integration ID
401	Invalid or missing API key
403	No access to this integration
404	Integration not found
429	Rate limit exceeded
500	Internal 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.

Overview

Completion API

Embedding API

Agents API

Integrations API

Skills API

Knowledge Folder API

Prompt Library API

Usage Export API

Workflow API

Scheduled Tasks API

User Management API

Billing API

Audit Logs API

Governance API

Compliance API

Update Auth Configuration

Before You Start

Base URL

Required Scopes

Parameters

Path Parameters

Request Body

Auth Types

Auth Field Schema

Field Types

OAuth Client Schema

Example: API Key Authentication

Response Format

Success Response (200 OK)

Behavior

Error Handling

​Before You Start

​Base URL

​Required Scopes

​Parameters

​Path Parameters

​Request Body

​Auth Types

​Auth Field Schema

​Field Types

​OAuth Client Schema

​Example: API Key Authentication

​Response Format

​Success Response (200 OK)

​Behavior

​Error Handling

Before You Start

Base URL

Required Scopes

Parameters

Path Parameters

Request Body

Auth Types

Auth Field Schema

Field Types

OAuth Client Schema

Example: API Key Authentication

Response Format

Success Response (200 OK)

Behavior

Error Handling