# Data integration A data integration represents a configured connection to a third-party [provider](https://workos.com/docs/reference/pipes/provider) through Pipes. Data integrations define the OAuth credentials, scopes, and settings used when users connect their accounts. For built-in providers, create a data integration by referencing the provider's slug. For custom providers, supply a `custom_provider` definition with the OAuth endpoints and configuration. #### Example data integration ## Endpoints - [Create a data integration](https://workos.com/docs/reference/pipes/data-integration/create) - [List data integrations](https://workos.com/docs/reference/pipes/data-integration/list) - [Get a data integration](https://workos.com/docs/reference/pipes/data-integration/get) - [Update a data integration](https://workos.com/docs/reference/pipes/data-integration/update) - [Delete a data integration](https://workos.com/docs/reference/pipes/data-integration/delete) ## Create a data integration Creates a [data integration](https://workos.com/docs/reference/pipes/data-integration) for a provider. Set `credentials.type` to `custom` to use your own OAuth app credentials, or `organization` to have each organization supply its own. For a built-in provider, pass its slug as `provider`. For a custom provider, pass a new slug plus a `custom_provider` definition. #### Request #### Response ### Error responses - **404 Not Found**: The provider slug does not match a built-in provider (and no `custom_provider` was supplied). - **422**: Invalid credentials configuration (e.g., missing `client_id`/`client_secret` for `custom` type, or supplying them for `organization` type). ## Delete a data integration Deletes a [data integration](https://workos.com/docs/reference/pipes/data-integration) by its provider slug. Returns `204 No Content` on success. This operation is idempotent — deleting a non-existent integration returns a successful response. Deleting a data integration also removes all associated connected accounts. #### Request ## Get a data integration Retrieves a data integration by its slug. #### Request #### Response ### Error responses - **404 Not Found**: No data integration exists for the given slug, or the integration uses unsupported credentials. ## List data integrations Lists the environment's data integrations configured with `custom` or `organization` credentials, including custom providers. #### Request #### Response ## Update a data integration Updates a [data integration](https://workos.com/docs/reference/pipes/data-integration) by its provider slug. Only the fields you include in the request body are updated; omitted fields are left unchanged. When `credentials` is provided, the stored client secret is rotated to the new value. The `custom_provider` block is only valid for custom-provider integrations. #### Request #### Response ### Error responses - **404 Not Found**: No data integration exists for the given slug. - **422**: Invalid credentials configuration or `custom_provider` supplied for a built-in provider integration. ### data_integration | Field | Type | Required | Description | | --- | --- | --- | --- | | `object` | "data_integration" | Yes | Distinguishes the data integration object. | | `id` | string | Yes | The unique identifier of the data integration. | | `slug` | string | Yes | The provider slug for this data integration. | | `integration_type` | string | Yes | The integration type derived from the provider. | | `description` | string \| null | Yes | An optional description of the data integration. | | `enabled` | boolean | Yes | Whether the data integration is enabled. | | `state` | "valid" \| "invalid" \| "requested" | Yes | The state of the data integration: `valid`: The integration is properly configured. `invalid`: The integration is not configured or has an error. `requested`: The integration has been requested but not yet configured. | | `scopes` | string[] \| null | Yes | The OAuth scopes configured for the data integration. `null` when the provider's configured scopes are used. | | `redirect_uri` | string | Yes | The OAuth redirect URI to register with the provider when configuring the custom application. | | `credentials` | object | Yes | The credentials configured for the data integration. | | `custom_provider` | object \| null | Yes | The OAuth definition when this is a custom provider; `null` for built-in providers. | | `created_at` | string | Yes | The timestamp when the data integration was created. | | `updated_at` | string | Yes | The timestamp when the data integration was last updated. | ### /data-integrations | Field | Type | Required | Description | | --- | --- | --- | --- | | `provider` | string | Yes | The provider to create a data integration for. For a built-in provider, use its slug (e.g., `github`, `slack`). For a custom provider, pass a new slug and supply `custom_provider`. | | `description` | string | No | An optional description of the data integration. | | `enabled` | boolean | No | Whether the data integration is enabled. Defaults to `false`. | | `scopes` | string[] | No | The OAuth scopes to request for the data integration. Defaults to the provider's configured scopes when omitted. | | `credentials` | object | No | The credentials to configure for the data integration. | | `custom_provider` | object | No | The OAuth definition for a custom provider. Supply this to define a custom provider; omit it to create an integration for a built-in provider. | ### DELETE /data-integrations/{slug} #### Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `slug` | string | Yes | The slug identifier of the data integration to delete. | #### Returns | Field | Type | Description | | --- | --- | --- | | `empty` | empty | Returns an empty response on success. | ### GET /data-integrations/{slug} #### Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `slug` | string | Yes | The slug identifier of the data integration (e.g., `github`, `slack`). | #### Returns | Field | Type | Description | | --- | --- | --- | | `data_integration` | object | Distinguishes the Data Integration object. | ### GET /data-integrations #### Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `before` | string | No | Pagination cursor to receive records before a provided data integration ID. | | `after` | string | No | Pagination cursor to receive records after a provided data integration ID. | | `limit` | integer | No | Maximum number of records to return. Accepts values between 1 and 100. Default is 10. | | `order` | "normal" \| "desc" \| "asc" | No | Sort order for the records. Accepts `asc`, `desc`, or `normal` (descending with reversed cursor semantics). Default is `desc`. | ### PUT /data-integrations/{slug} #### Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `slug` | string | Yes | The slug identifier of the data integration to update. | #### Returns | Field | Type | Description | | --- | --- | --- | | `data_integration` | object | Distinguishes the Data Integration object. |