---
title: "Update connector configuration"
method: PUT
path: "/connectors/{connectorId}/config"
tags: ["Connector Configuration"]
---

# Update connector configuration

`PUT /connectors/{connectorId}/config`

## Request

- Base URL: `https://app.pipeshub.com/api/v1`
- URL: `https://app.pipeshub.com/api/v1/connectors/{connectorId}/config`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/api/v1/oauth2/authorize`
    - Client credentials
    - Token URL: `/api/v1/oauth2/token` scopes: `connector:write`, `connector:read`

Update authentication, sync, and filter configuration.<br><br>
<b>Prerequisites:</b><br>
Connector must be <b>disabled</b> before updating configuration.
Disable it first using <code>POST /{id}/toggle</code>.<br><br>
<b>Partial Updates:</b><br>
Only provide the sections you want to update. Omitted sections
are not modified.<br><br>
<b>Secrets:</b><br>
A secret field in <code>auth</code> sent as <code>••••••••</code> keeps the
stored value, so the configuration can be sent back as it was read. The
response masks stored secrets the same way.<br><br>
<b>Signing out:</b><br>
A change to <code>auth</code>, a different top-level <code>oauthConfigId</code>,
or a linked OAuth app that now holds a different client signs the connector
out and clears its OAuth tokens. Sending <code>auth</code> back as it was read,
with secrets as the mask or in full, keeps it signed in.<br><br>
<b>OAuth apps (OAUTH connectors):</b><br>
An OAUTH connector signs in with the client ID and secret of its linked OAuth
app, so client credentials an admin sends in <code>auth</code> go into an app,
as on <code>PUT /{connectorId}/config/auth</code>:
<ul>
  <li>On a connector with no app, an app is created from them and linked
  (<code>auth.oauthConfigId</code> in the response) once every required OAuth
  field is present; until then the values are kept on the connector.</li>
  <li>On a linked connector, changed values update the app named in
  <code>auth.oauthConfigId</code>, and only the fields that changed. Without that
  field a new app is created and linked; the previously linked app, which other
  connectors may share, is not changed.</li>
  <li>The new app is named <code>auth.oauthInstanceName</code>, or else after the
  connector.</li>
</ul>
A linked connector stores no copy of its app's secret fields: they are not
stored, and not returned, in <code>config.auth</code>. Its client ID and provider
URLs are the app's. Only an admin's credentials create or change an app.

## Path parameters

- `connectorId` string, required

## Request body

- UpdateConnectorConfigRequest: Request to update connector configuration (partial updates supported)
  - `auth` ConnectorAuthConfig: Auth settings, flat: send each field listed under `auth.schemas.<authType>.fields` in GET /connectors/registry/{connectorType}/schema by its `name`. For OAuth, an admin may send the OAuth app's credentials here (the app is saved and linked), or anyone may send `oauthConfigId` to use a saved app.
    - `oauthConfigId` string: A saved OAuth app (GET /oauth/{connectorType})
    - `oauthInstanceName` string: Name for the OAuth app saved from inline credentials
    - `connectorScope` string: Scope of the instance, as the frontend sends it; the server fills it in when absent
    - `authType` string: On `PUT /connectors/{connectorId}/config` only: must equal the instance's `authType`, which cannot be changed (`400` otherwise).
  - `sync` ConnectorSyncConfig: Sync strategy plus connector-specific sync settings, flat: send each field listed under `sync.customFields` in the registry schema by its `name`.
    - `selectedStrategy` 'MANUAL' | 'SCHEDULED' | 'WEBHOOK'
    - `scheduledConfig` object
      - `intervalMinutes` integer
      - `timezone` string
      - `startTime` integer: Epoch milliseconds
      - `startDateTime` unknown
    - `webhookConfig` object
      - `webhookUrl` string
      - `events` string[]
  - `filters` ConnectorFiltersConfig
    - `sync` object
      - `values` object
    - `indexing` object
      - `values` object
  - `baseUrl` string: Base URL for self-hosted instances. Any string is accepted; it is not checked to be a URL.

## Response `200`

Configuration updated

- object
  - `success` boolean, required
  - `config` ConnectorStoredConfig, required: A connector instance's saved settings. Secret auth fields come back masked; saving the mask back keeps the stored value. Provider OAuth tokens are never returned.
    - `auth` object: Auth fields for the instance's auth type, keyed by field name
      - `authType` 'OAUTH' | 'OAUTH_ADMIN_CONSENT' | 'API_TOKEN' | 'BEARER_TOKEN' | 'BASIC_AUTH' | 'ACCESS_KEY' | 'IAM_ROLE' | 'ACCOUNT_KEY' | 'CONNECTION_STRING' | 'ENTRA_ID' | 'CUSTOM' | 'NONE': How a connector instance signs in to its source. Each connector type supports a subset; see `supportedAuthTypes` in the registry.
      - `connectorType` string: Set by the server to the instance's connector type
      - `connectorScope` 'team' | 'personal': Scope determines visibility and access control for connectors:<br> <ul> <li><code>team</code> - Available to all users in the organization (admin-only creation)</li> <li><code>personal</code> - Private to the creating user only</li> </ul>
      - `oauthConfigId` string: The shared OAuth app the instance signs in with
      - `oauthInstanceName` string
      - `redirectUri` string: OAuth redirect URI the server built for this instance
    - `sync` object: Sync strategy plus connector-specific sync settings
      - `selectedStrategy` string: `MANUAL`, `SCHEDULED` or `WEBHOOK`
      - `scheduledConfig` object: Schedule used when `selectedStrategy` is `SCHEDULED`
      - `customValues` object: Values of the connector's own sync fields
    - `filters` object: Saved filter selections
      - `sync` object: What to fetch from the source. Selections are under `values`, keyed by filter name.
      - `indexing` object: Which fetched records to index. Selections are under `values`, keyed by filter name.
  - `message` string

## Other responses

- `400`: Refused. Possible reasons:<br> <ul> <li><code>VALIDATION_ERROR</code> - <code>baseUrl</code> is not a string</li> <li><code>filters.sync</code> or <code>filters.indexing</code> is present but not an object</li> <li><code>auth</code> is present but not an object ("Auth configuration must be an object.")</li> <li><code>auth.authType</code> differs from the instance's auth type, which is locked after creation</li> <li>A required sync filter of the connector type is not set</li> <li>The connector is active: disable it before updating</li> <li>The connector ID is an unsafe path segment</li> <li>For an OAUTH connector: a new client ID sent without its client secret; a replacement OAuth app that would lack a required field; or a client secret sent while the connector still lacks its own authorize and token URLs (ServiceNow). Nothing is stored.</li> </ul>
- `401`: Missing or invalid credentials
- `403`: The token lacks a required scope, or the caller may not use this connector
- `404`: Connector, or the OAuth app named in <code>auth.oauthConfigId</code>, not found. For the connector: also when it is not visible to the caller (another user's personal connector, or another user's team connector for a member). Also the answer for an ID of the wrong shape: this route does not check it.
- `409`: The connector is locked by a sync or deletion in progress, or an OAuth app with the name the new app would take already exists in the organization. For a name collision, send a different <code>auth.oauthInstanceName</code>, or name the app to update in <code>auth.oauthConfigId</code>.
- `500`: The configuration, or the OAuth app, could not be saved. An app this request created is removed, and an app it updated is put back. A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.

## Changes

- **2026-10-28** `dbb5e203b445`: 9 info
  - added the new optional request property `auth/authType`
  - added the new optional request property `auth/connectorScope`
  - added the new optional request property `sync/scheduledConfig/startDateTime`
  - the `baseUrl` request property format was generalized from `uri` to no format
  - …5 more
- **2026-10-26** `fc76aa045994`: 2 warning
  - added the new `ENTRA_ID` enum value to the `config/auth/authType` response property for the response status `200`
  - added the new `IAM_ROLE` enum value to the `config/auth/authType` response property for the response status `200`
- **2026-10-15** `a44792e4f0e6`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/changes/connectors/:connectorId/config/put.md)

---

[API](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api.md) - [All operations](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pipeshub-ai/apis/pipeshub-api/revisions/dbb5e203b445?raw)