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
| 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 OAUTH / OAUTH_DCR auth types) |
Auth Types
| Type | Description |
|---|
NONE | No authentication required |
API_KEY | Users provide credentials via custom auth fields |
SERVICE_ACCOUNT | Service-level credentials via auth fields |
OAUTH | OAuth 2.0 flow with authorization code |
OAUTH_DCR | OAuth 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.
| 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 or OAUTH_DCR.
| 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) |
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 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");
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 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.