> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Auth Configuration

> Configure authentication for a custom integration

<Info>
  **Using our API via a dedicated deployment?** Just replace `api.langdock.com` with your deployment's base URL: **`<deployment-url>/api/public`**
</Info>

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.

<Warning>
  Changing the `authType` **deletes all existing user connections** to this integration. Users will need to reconnect.
</Warning>

## 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 |
| `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`)     |

<Info>
  The `slug` must be unique within the integration. The field `id` is auto-generated — do not include it in the request.
</Info>

### 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)          |

<Warning>
  OAuth credentials (`clientId`, `clientSecret`, `authUrl`, `tokenUrl`) are **write-only** — they are never returned in API responses.
</Warning>

## Example: API Key Authentication

```javascript theme={null}
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)

```typescript theme={null}
{
  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                  |

<Info>
  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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>