A data integration represents a configured connection to a third-party 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
JSON
data_integration
Creates a 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.
cURL
| curl --request POST \ | |
| --url "https://api.workos.com/data-integrations" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "provider": "github" | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.pipes.create_data_integration(provider: "github") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.pipes.create_data_integration(provider="github") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Pipes().CreateDataIntegration(context.Background(), &workos.PipesCreateDataIntegrationParams{ | |
| Provider: "github", | |
| }) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->pipes()->createDataIntegration(provider: "github"); |
| import com.workos.WorkOS; | |
| import com.workos.pipes.PipesApi.CreateDataIntegrationOptions; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| CreateDataIntegrationOptions options = | |
| CreateDataIntegrationOptions.builder().provider("github").build(); | |
| workos.pipes.createDataIntegration(options); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Pipes.CreateDataIntegrationAsync(new PipesCreateDataIntegrationOptions { | |
| Provider = "github", | |
| }); |
| use workos::Client; | |
| use workos::pipes::CreateDataIntegrationParams; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .pipes() | |
| .create_data_integration( | |
| CreateDataIntegrationParams { | |
| provider: "github".into(), | |
| ..Default::default() | |
| } | |
| ) | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "data_integration", | |
| "id": "data_integration_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "slug": "github", | |
| "integration_type": "github", | |
| "description": "Production GitHub app", | |
| "enabled": true, | |
| "state": "valid", | |
| "scopes": [ | |
| "repo", | |
| "read:org" | |
| ], | |
| "redirect_uri": "https://api.workos.com/data-integrations/github/dik_01EHZNVPK3SFK441A1RGBFSHRT/callback", | |
| "credentials": { | |
| "type": "custom", | |
| "client_id": "Iv1.abc123", | |
| "redacted_client_secret": "6789" | |
| }, | |
| "custom_provider": { | |
| "name": "My OAuth App", | |
| "authorization_url": "https://provider.example.com/oauth/authorize", | |
| "token_url": "https://provider.example.com/oauth/token", | |
| "refresh_token_url": "https://provider.example.com/oauth/token", | |
| "pkce_enabled": true, | |
| "request_scope_separator": " ", | |
| "scopes_required": false, | |
| "client_secret_required": true, | |
| "additional_authorization_parameters": { | |
| "prompt": "consent" | |
| }, | |
| "token_body_content_type": "application/x-www-form-urlencoded", | |
| "authenticate_via": "request_body" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
POST/data-integrations
Returns
- 404 Not Found: The provider slug does not match a built-in provider (and no
custom_providerwas supplied). - 422: Invalid credentials configuration (e.g., missing
client_id/client_secretforcustomtype, or supplying them fororganizationtype).
Lists the environment’s data integrations configured with custom or organization credentials, including custom providers.
cURL
| curl "https://api.workos.com/data-integrations" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.pipes.list_data_integrations |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.pipes.list_data_integrations() |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Pipes().ListDataIntegrations(context.Background()) | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->pipes()->listDataIntegrations(); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.pipes.listDataIntegrations(); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Pipes.ListDataIntegrationsAsync(); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .pipes() | |
| .list_data_integrations() | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "list", | |
| "data": [ | |
| { | |
| "object": "data_integration", | |
| "id": "data_integration_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "slug": "github", | |
| "integration_type": "github", | |
| "description": "Production GitHub app", | |
| "enabled": true, | |
| "state": "valid", | |
| "scopes": [ | |
| "repo", | |
| "read:org" | |
| ], | |
| "redirect_uri": "https://api.workos.com/data-integrations/github/dik_01EHZNVPK3SFK441A1RGBFSHRT/callback", | |
| "credentials": { | |
| "type": "custom", | |
| "client_id": "Iv1.abc123", | |
| "redacted_client_secret": "6789" | |
| }, | |
| "custom_provider": { | |
| "name": "My OAuth App", | |
| "authorization_url": "https://provider.example.com/oauth/authorize", | |
| "token_url": "https://provider.example.com/oauth/token", | |
| "refresh_token_url": "https://provider.example.com/oauth/token", | |
| "pkce_enabled": true, | |
| "request_scope_separator": " ", | |
| "scopes_required": false, | |
| "client_secret_required": true, | |
| "additional_authorization_parameters": { | |
| "prompt": "consent" | |
| }, | |
| "token_body_content_type": "application/x-www-form-urlencoded", | |
| "authenticate_via": "request_body" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } | |
| ], | |
| "list_metadata": { | |
| "before": "data_integration_01HXYZ123456789ABCDEFGHIJ", | |
| "after": "data_integration_01HXYZ987654321KJIHGFEDCBA" | |
| } | |
| } |
Feature flagged
GET/data-integrations
Parameters
Returns object
Retrieves a data integration by its slug.
cURL
| curl "https://api.workos.com/data-integrations/github" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.pipes.get_data_integration(slug: "github") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.pipes.get_data_integration(slug="github") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Pipes().GetDataIntegration(context.Background(), "github") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->pipes()->getDataIntegration(slug: "github"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.pipes.getDataIntegration("github"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Pipes.GetDataIntegrationAsync("github"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .pipes() | |
| .get_data_integration("github") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "data_integration", | |
| "id": "data_integration_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "slug": "github", | |
| "integration_type": "github", | |
| "description": "Production GitHub app", | |
| "enabled": true, | |
| "state": "valid", | |
| "scopes": [ | |
| "repo", | |
| "read:org" | |
| ], | |
| "redirect_uri": "https://api.workos.com/data-integrations/github/dik_01EHZNVPK3SFK441A1RGBFSHRT/callback", | |
| "credentials": { | |
| "type": "custom", | |
| "client_id": "Iv1.abc123", | |
| "redacted_client_secret": "6789" | |
| }, | |
| "custom_provider": { | |
| "name": "My OAuth App", | |
| "authorization_url": "https://provider.example.com/oauth/authorize", | |
| "token_url": "https://provider.example.com/oauth/token", | |
| "refresh_token_url": "https://provider.example.com/oauth/token", | |
| "pkce_enabled": true, | |
| "request_scope_separator": " ", | |
| "scopes_required": false, | |
| "client_secret_required": true, | |
| "additional_authorization_parameters": { | |
| "prompt": "consent" | |
| }, | |
| "token_body_content_type": "application/x-www-form-urlencoded", | |
| "authenticate_via": "request_body" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
GET/data-integrations
Parameters
Returns
- 404 Not Found: No data integration exists for the given slug, or the integration uses unsupported credentials.
Updates a 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.
cURL
| curl --request PUT \ | |
| --url "https://api.workos.com/data-integrations/github" \ | |
| --header "Authorization: Bearer sk_example_123456789" \ | |
| --header "Content-Type: application/json" \ | |
| -d @- <<'BODY' | |
| { | |
| "description": "Production GitHub app", | |
| "enabled": true, | |
| "scopes": [ | |
| "repo", | |
| "read:org" | |
| ], | |
| "credentials": { | |
| "type": "custom", | |
| "client_id": "Iv1.abc123", | |
| "client_secret": "secret_…" | |
| }, | |
| "custom_provider": { | |
| "name": "My OAuth App", | |
| "authorization_url": "https://provider.example.com/oauth/authorize", | |
| "token_url": "https://provider.example.com/oauth/token", | |
| "refresh_token_url": "https://provider.example.com/oauth/token", | |
| "pkce_enabled": true, | |
| "request_scope_separator": " ", | |
| "scopes_required": false, | |
| "client_secret_required": true, | |
| "additional_authorization_parameters": { | |
| "prompt": "consent" | |
| }, | |
| "token_body_content_type": "application/x-www-form-urlencoded", | |
| "authenticate_via": "request_body" | |
| } | |
| } | |
| BODY |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.pipes.update_data_integration(slug: "github") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.pipes.update_data_integration(slug="github") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Pipes().UpdateDataIntegration(context.Background(), "github") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->pipes()->updateDataIntegration(slug: "github"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.pipes.updateDataIntegration("github"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Pipes.UpdateDataIntegrationAsync("github"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .pipes() | |
| .update_data_integration("github") | |
| .await?; | |
| Ok(()) | |
| } |
| { | |
| "object": "data_integration", | |
| "id": "data_integration_01EHZNVPK3SFK441A1RGBFSHRT", | |
| "slug": "github", | |
| "integration_type": "github", | |
| "description": "Production GitHub app", | |
| "enabled": true, | |
| "state": "valid", | |
| "scopes": [ | |
| "repo", | |
| "read:org" | |
| ], | |
| "redirect_uri": "https://api.workos.com/data-integrations/github/dik_01EHZNVPK3SFK441A1RGBFSHRT/callback", | |
| "credentials": { | |
| "type": "custom", | |
| "client_id": "Iv1.abc123", | |
| "client_secret": "secret_…" | |
| }, | |
| "custom_provider": { | |
| "name": "My OAuth App", | |
| "authorization_url": "https://provider.example.com/oauth/authorize", | |
| "token_url": "https://provider.example.com/oauth/token", | |
| "refresh_token_url": "https://provider.example.com/oauth/token", | |
| "pkce_enabled": true, | |
| "request_scope_separator": " ", | |
| "scopes_required": false, | |
| "client_secret_required": true, | |
| "additional_authorization_parameters": { | |
| "prompt": "consent" | |
| }, | |
| "token_body_content_type": "application/x-www-form-urlencoded", | |
| "authenticate_via": "request_body" | |
| }, | |
| "created_at": "2026-01-15T12:00:00.000Z", | |
| "updated_at": "2026-01-15T12:00:00.000Z" | |
| } |
Feature flagged
PUT/data-integrations
Parameters
Returns
- 404 Not Found: No data integration exists for the given slug.
- 422: Invalid credentials configuration or
custom_providersupplied for a built-in provider integration.
Deletes a 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.
cURL
| curl --request DELETE \ | |
| --url "https://api.workos.com/data-integrations/github" \ | |
| --header "Authorization: Bearer sk_example_123456789" |
| require "workos" | |
| WorkOS.configure do |config| | |
| config.api_key = "sk_example_123456789" | |
| end | |
| WorkOS.client.pipes.delete_data_integration(slug: "github") |
| from workos import WorkOSClient | |
| client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789") | |
| client.pipes.delete_data_integration(slug="github") |
| package main | |
| import ( | |
| "context" | |
| "github.com/workos/workos-go/v9" | |
| ) | |
| func main() { | |
| client := workos.NewClient("sk_example_123456789") | |
| _, err := client.Pipes().DeleteDataIntegration(context.Background(), "github") | |
| if err != nil { | |
| panic(err) | |
| } | |
| } |
| <?php | |
| use WorkOS\WorkOS; | |
| $workos = new WorkOS( | |
| apiKey: "sk_example_123456789", | |
| clientId: "client_123456789", | |
| ); | |
| $workos->pipes()->deleteDataIntegration(slug: "github"); |
| import com.workos.WorkOS; | |
| WorkOS workos = new WorkOS("sk_example_123456789"); | |
| workos.pipes.deleteDataIntegration("github"); |
| using WorkOS; | |
| var client = new WorkOSClient(new WorkOSOptions { | |
| ApiKey = "sk_example_123456789", | |
| ClientId = "client_123456789", | |
| }); | |
| await client.Pipes.DeleteDataIntegrationAsync("github"); |
| use workos::Client; | |
| #[tokio::main] | |
| async fn main() -> Result<(), workos::Error> { | |
| let client = Client::builder() | |
| .api_key("sk_example_123456789") | |
| .client_id("client_123456789") | |
| .build(); | |
| let _result = client | |
| .pipes() | |
| .delete_data_integration("github") | |
| .await?; | |
| Ok(()) | |
| } |
Feature flagged
DELETE/data-integrations
Parameters
Returns
Connected account Continue to the next section
Up next