<!-- llms.txt: https://workos.com/llms.txt -->
<!-- feedback.md: https://workos.com/docs/feedback.md -->

# Connected account

A connected account represents a user's authorized connection to a third-party [provider](https://workos.com/docs/reference/pipes/provider) through Pipes. Connected accounts store the OAuth credentials and scopes granted during the authorization flow.

When listing providers for a user, each provider includes a nested `connected_account` showing the user's connection status.

## Create another API key connected account

Creates another API key-based connected account for the specified integration, owned by the user or, when `connection_owner` is `organization`, shared by the organization. Requires `connection_intent: add` and does not accept `connected_account_id`; use PUT to create or rotate the compatibility connection or to update an exact connection.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/data-integrations/github/api-key" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
        "account_identifier": "workspace_123",
        "account_display_name": "Acme production",
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "secret": "sk-1234567890abcdef",
        "connection_intent": "add"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.create_data_integration_api_key(
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  secret: "sk-1234567890abcdef",
  connection_intent: "add"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.create_data_integration_api_key(
    slug="github",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
    secret="sk-1234567890abcdef",
    connection_intent="add",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().CreateDataIntegrationAPIKey(context.Background(), "github", &workos.PipesCreateDataIntegrationAPIKeyParams{
		UserID:           "user_01EHZNVPK3SFK441A1RGBFSHRT",
		Secret:           "sk-1234567890abcdef",
		ConnectionIntent: "add",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->createDataIntegrationApiKey(
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        secret: "sk-1234567890abcdef",
        connectionIntent: "add",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.CreateDataIntegrationApiKeyOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateDataIntegrationApiKeyOptions options =
    CreateDataIntegrationApiKeyOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .secret("sk-1234567890abcdef")
        .connectionIntent("add")
        .build();

workos.pipes.createDataIntegrationApiKey("github", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.CreateDataIntegrationApiKeyAsync("github", new PipesCreateDataIntegrationApiKeyOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
    Secret = "sk-1234567890abcdef",
    ConnectionIntent = "add",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::pipes::CreateDataIntegrationApiKeyParams;

#[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_api_key(
            "github",
            CreateDataIntegrationApiKeyParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                secret: "sk-1234567890abcdef".into(),
                connection_intent: "add".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "standard",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "scopes": [],
  "auth_method": "api_key",
  "api_key_last_4": "cdef",
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Create another client credentials connected account

Creates another client credentials-based connected account for the specified integration, owned by the user or, when `connection_owner` is `organization`, shared by the organization. Requires `connection_intent: add` and does not accept `connected_account_id`; use PUT to create or rotate the compatibility connection or to update an exact connection.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/data-integrations/salesforce/client-credentials" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
        "account_identifier": "workspace_123",
        "account_display_name": "Acme production",
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "client_id": "3MVG9...",
        "client_secret": "shhh-secret",
        "connection_intent": "add"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.create_data_integration_client_credential(
  slug: "salesforce",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  client_id: "3MVG9...",
  client_secret: "shhh-secret",
  connection_intent: "add"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.create_data_integration_client_credential(
    slug="salesforce",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
    client_id="3MVG9...",
    client_secret="shhh-secret",
    connection_intent="add",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().CreateDataIntegrationClientCredential(context.Background(), "salesforce", &workos.PipesCreateDataIntegrationClientCredentialParams{
		UserID:           "user_01EHZNVPK3SFK441A1RGBFSHRT",
		ClientID:         "3MVG9...",
		ClientSecret:     "shhh-secret",
		ConnectionIntent: "add",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->createDataIntegrationClientCredential(
        slug: "salesforce",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        clientId: "3MVG9...",
        clientSecret: "shhh-secret",
        connectionIntent: "add",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.CreateDataIntegrationClientCredentialOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateDataIntegrationClientCredentialOptions options =
    CreateDataIntegrationClientCredentialOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .clientId("3MVG9...")
        .clientSecret("shhh-secret")
        .connectionIntent("add")
        .build();

workos.pipes.createDataIntegrationClientCredential("salesforce", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.CreateDataIntegrationClientCredentialAsync("salesforce",
                                                              new PipesCreateDataIntegrationClientCredentialOptions {
                                                                  UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
                                                                  ClientId = "3MVG9...",
                                                                  ClientSecret = "shhh-secret",
                                                                  ConnectionIntent = "add",
                                                              });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::pipes::CreateDataIntegrationClientCredentialParams;

#[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_client_credential(
            "salesforce",
            CreateDataIntegrationClientCredentialParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                client_id: "3MVG9...".into(),
                client_secret: "shhh-secret".into(),
                connection_intent: "add".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "standard",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "scopes": [],
  "auth_method": "client_credentials",
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Import an organization connected account

Imports an organization-owned [connected account](https://workos.com/docs/reference/pipes/connected-account) by providing OAuth tokens directly. Omit `connection_intent` to create only the compatibility connection, or set it to `add` to explicitly create another connection. This creation-only endpoint does not accept `connected_account_id` or reauthorization intent.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organizations_data_providers.create_organization_connected_account(
  organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organizations_data_providers.create_organization_connected_account(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT",
    slug="github",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.OrganizationsDataProviders().CreateConnectedAccount(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "github", &workos.OrganizationsDataProvidersCreateConnectedAccountParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationsDataProviders()
    ->createOrganizationConnectedAccount(
        organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.organizationsdataproviders.OrganizationsDataProvidersApi.CreateOrganizationConnectedAccountOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateOrganizationConnectedAccountOptions options =
    CreateOrganizationConnectedAccountOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .build();

workos.organizationsDataProviders.createOrganizationConnectedAccount(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationsDataProviders.CreateConnectedAccountAsync(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github",
    new OrganizationsDataProvidersCreateConnectedAccountOptions {
        UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
    });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::organizations_data_providers::CreateOrganizationConnectedAccountParams;

#[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
        .organizations_data_providers()
        .create_organization_connected_account(
            "org_01EHZNVPK3SFK441A1RGBFSHRT",
            "github",
            CreateOrganizationConnectedAccountParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "user_id": null,
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Create a connected account

Imports a [connected account](https://workos.com/docs/reference/pipes/connected-account) for a user by directly providing OAuth tokens. This is useful for migrating existing connections from another system.

The `state` field is derived from the token combination when not explicitly set. If no tokens are provided, the state defaults to `needs_reauthorization`.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.create_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.create_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().CreateUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->createUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.createUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.CreateUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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()
        .create_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": null,
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z",
  "warnings": [
    {
      "code": "duplicate_account_display_name",
      "message": "Another connection for this provider and owner has the same label."
    }
  ]
}
```

:::

> **Note:** Token combinations are validated on create. Invalid combinations — such as providing only `expires_at` without an `access_token` — will return a `422` error. See the token validation rules below.

### Token validation

When creating a connected account, the following token combination rules apply:

- No tokens provided → `state` is set to `needs_reauthorization`.
- `access_token` with `expires_at` and `refresh_token` → valid, `state` is `connected`.
- `access_token` only (no `expires_at`) → valid, `state` is `connected`.
- `access_token` with `expires_at` but no `refresh_token` → rejected (`422`).
- `refresh_token` only (no `access_token`) → valid, `expires_at` is set to now.
- `expires_at` only (no `access_token`) → rejected (`422`).

### Error responses

- **409 Conflict**: A connected account already exists for this user, integration, and organization.
- **422**: Invalid token combination or the data integration is not in a valid state.

## Delete an organization connected account

Disconnects the organization's account for the provider, including removing any stored access and refresh tokens. A member will need to reauthorize if the organization wants to reconnect. This does not revoke access on the provider side.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organizations_data_providers.delete_organization_connected_account(
  organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organizations_data_providers.delete_organization_connected_account(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.OrganizationsDataProviders().DeleteConnectedAccount(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationsDataProviders()
    ->deleteOrganizationConnectedAccount(
        organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationsDataProviders.deleteOrganizationConnectedAccount(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationsDataProviders.DeleteConnectedAccountAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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
        .organizations_data_providers()
        .delete_organization_connected_account(
            "org_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

:::

## Delete a connected account

Disconnects WorkOS's account for the user, including removing any stored access and refresh tokens. The user will need to reauthorize if they want to reconnect.

This does not revoke access on the provider side. The user may need to disconnect the application directly from the provider's settings.

Returns a `204 No Content` response on success.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request DELETE \
  --url "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.pipes.deleteUserConnectedAccount({
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
  slug: 'github',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.delete_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.delete_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().DeleteUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->deleteUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.deleteUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.DeleteUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

:::

## Get authorization URL

Generates an OAuth authorization URL to initiate the connection flow for a user. Redirect the user to the returned URL to begin the OAuth flow with the third-party provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/data-integrations/github/authorize" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const { url } = await workos.pipes.authorizeDataIntegration({
  slug: 'github',
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
});
```

```rb language="ruby" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.authorize_data_integration(
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```py language="python" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.authorize_data_integration(
    slug="github", user_id="user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```go language="go" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().AuthorizeDataIntegration(context.Background(), "github", &workos.PipesAuthorizeDataIntegrationParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->authorizeDataIntegration(
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
    );
```

```java language="java" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports
// optional-intent unions
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.AuthorizeDataIntegrationOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

AuthorizeDataIntegrationOptions options = AuthorizeDataIntegrationOptions.builder()
                                              .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
                                              .build();

workos.pipes.authorizeDataIntegration("github", options);
```

```cs language="dotnet" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.AuthorizeDataIntegrationAsync("github", new PipesAuthorizeDataIntegrationOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
});
```

```rust language="rust" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
use workos::Client;
use workos::pipes::AuthorizeDataIntegrationParams;

#[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()
        .authorize_data_integration(
            "github",
            AuthorizeDataIntegrationParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "url": "https://api.workos.com/data-integrations/q2czJKmVAraSBg8xFpT7M9uR/authorize-redirect"
}
```

:::

## Get an organization connected account

Retrieves an organization's [connected account](https://workos.com/docs/reference/pipes/connected-account) for a specific provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organizations_data_providers.get_organization_connected_account(
  organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organizations_data_providers.get_organization_connected_account(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.OrganizationsDataProviders().GetConnectedAccount(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationsDataProviders()
    ->getOrganizationConnectedAccount(
        organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationsDataProviders.getOrganizationConnectedAccount(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationsDataProviders.GetConnectedAccountAsync("org_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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
        .organizations_data_providers()
        .get_organization_connected_account(
            "org_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "user_id": null,
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## List providers for an organization

Retrieves the organization-owned providers configured for your environment and the organization's [connected account](https://workos.com/docs/reference/pipes/connected-account) information for each. Providers owned by individual users are not included.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/data_providers" \
  --header "Authorization: Bearer sk_example_123456789"
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organizations_data_providers.list_organization_data_providers(organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organizations_data_providers.list_organization_data_providers(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.OrganizationsDataProviders().List(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationsDataProviders()
    ->listOrganizationDataProviders(
        organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.organizationsDataProviders.listOrganizationDataProviders(
    "org_01EHZNVPK3SFK441A1RGBFSHRT");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationsDataProviders.ListAsync("org_01EHZNVPK3SFK441A1RGBFSHRT");
```

```rust language="rust" title="Request" tab="1"
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
        .organizations_data_providers()
        .list_organization_data_providers("org_01EHZNVPK3SFK441A1RGBFSHRT")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "data_provider",
      "id": "data_integration_01EHZNVPK3SFK441A1RGBFSHRT",
      "name": "GitHub",
      "description": "Connect your GitHub account to access repositories.",
      "slug": "github",
      "integration_type": "github",
      "credentials_type": "oauth2",
      "scopes": [
        "repo",
        "user:email"
      ],
      "auth_methods": [
        "oauth"
      ],
      "connection_owner": "organization",
      "ownership": "organization",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "integrationType": "github",
      "credentialsType": "oauth2",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z",
      "connected_account": {
        "object": "connected_account",
        "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
        "user_id": null,
        "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
        "connection_role": "compatibility",
        "account_identifier": "workspace_123",
        "account_display_name": "Acme production",
        "scopes": [
          "repo",
          "user:email"
        ],
        "auth_method": "oauth",
        "api_key_last_4": null,
        "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
        "client_secret_last_4": "cdef",
        "config": {
          "instance_url": "https://example.my.salesforce.com"
        },
        "state": "connected",
        "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "state_reason": null,
        "created_at": "2024-01-16T14:20:00.000Z",
        "updated_at": "2024-01-16T14:20:00.000Z",
        "userlandUserId": null,
        "organizationId": "org_01EHZNVPK3SFK441A1RGBFSHRT",
        "createdAt": "2024-01-16T14:20:00.000Z",
        "updatedAt": "2024-01-16T14:20:00.000Z"
      },
      "connected_accounts": [
        {
          "object": "connected_account",
          "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
          "user_id": null,
          "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
          "connection_role": "compatibility",
          "account_identifier": "workspace_123",
          "account_display_name": "Acme production",
          "scopes": [
            "repo",
            "user:email"
          ],
          "auth_method": "oauth",
          "api_key_last_4": null,
          "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
          "client_secret_last_4": "cdef",
          "config": {
            "instance_url": "https://example.my.salesforce.com"
          },
          "state": "connected",
          "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
          "state_reason": null,
          "created_at": "2024-01-16T14:20:00.000Z",
          "updated_at": "2024-01-16T14:20:00.000Z",
          "userlandUserId": null,
          "organizationId": "org_01EHZNVPK3SFK441A1RGBFSHRT",
          "createdAt": "2024-01-16T14:20:00.000Z",
          "updatedAt": "2024-01-16T14:20:00.000Z"
        }
      ]
    }
  ]
}
```

:::

## Get a connected account

Retrieves a user's [connected account](https://workos.com/docs/reference/pipes/connected-account) for a specific provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const connectedAccount = await workos.pipes.getUserConnectedAccount({
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
  slug: 'github',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.get_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.get_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().GetUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->getUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.getUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.GetUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": null,
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Update an organization connected account

Updates an organization's [connected account](https://workos.com/docs/reference/pipes/connected-account) tokens, scopes, or state for a specific provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/organizations/org_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.organizations_data_providers.update_organization_connected_account(
  organization_id: "org_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.organizations_data_providers.update_organization_connected_account(
    organization_id="org_01EHZNVPK3SFK441A1RGBFSHRT",
    slug="github",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.OrganizationsDataProviders().UpdateConnectedAccount(context.Background(), "org_01EHZNVPK3SFK441A1RGBFSHRT", "github", &workos.OrganizationsDataProvidersUpdateConnectedAccountParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->organizationsDataProviders()
    ->updateOrganizationConnectedAccount(
        organizationId: "org_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.organizationsdataproviders.OrganizationsDataProvidersApi.UpdateOrganizationConnectedAccountOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateOrganizationConnectedAccountOptions options =
    UpdateOrganizationConnectedAccountOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .build();

workos.organizationsDataProviders.updateOrganizationConnectedAccount(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.OrganizationsDataProviders.UpdateConnectedAccountAsync(
    "org_01EHZNVPK3SFK441A1RGBFSHRT", "github",
    new OrganizationsDataProvidersUpdateConnectedAccountOptions {
        UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
    });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::organizations_data_providers::UpdateOrganizationConnectedAccountParams;

#[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
        .organizations_data_providers()
        .update_organization_connected_account(
            "org_01EHZNVPK3SFK441A1RGBFSHRT",
            "github",
            UpdateOrganizationConnectedAccountParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "user_id": null,
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Update a connected account

Updates a user's [connected account](https://workos.com/docs/reference/pipes/connected-account) tokens, scopes, or state for a specific provider.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/user_management/users/user_01EHZNVPK3SFK441A1RGBFSHRT/connected_accounts/github" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "account_display_name": "Acme production",
        "account_identifier": "workspace_123",
        "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
        "refresh_token": "ghr_xxxxxxxxxxxxxxxxxxxx",
        "expires_at": "2025-12-31T23:59:59.000Z",
        "scopes": [
            "repo",
            "user:email"
        ],
        "state": "connected"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.update_user_connected_account(
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  slug: "github"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.update_user_connected_account(
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT", slug="github"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().UpdateUserConnectedAccount(context.Background(), "user_01EHZNVPK3SFK441A1RGBFSHRT", "github")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->updateUserConnectedAccount(
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        slug: "github",
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.pipes.updateUserConnectedAccount("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.UpdateUserConnectedAccountAsync("user_01EHZNVPK3SFK441A1RGBFSHRT", "github");
```

```rust language="rust" title="Request" tab="1"
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_user_connected_account(
            "user_01EHZNVPK3SFK441A1RGBFSHRT",
            "github"
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": null,
  "scopes": [
    "repo",
    "user:email"
  ],
  "auth_method": "oauth",
  "api_key_last_4": null,
  "client_id": "3MVG9dZJodJWxft2VoStSCVwPFsx0eDcpVc",
  "client_secret_last_4": "cdef",
  "config": {
    "instance_url": "https://example.my.salesforce.com"
  },
  "state": "connected",
  "established_by_user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "state_reason": null,
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z",
  "warnings": [
    {
      "code": "duplicate_account_display_name",
      "message": "Another connection for this provider and owner has the same label."
    }
  ]
}
```

:::

> **Note:** Unlike the create endpoint, update does **not** validate token combinations. The provided values are applied directly, so callers are responsible for maintaining valid token and state combinations. For example, setting `state` to `connected` without providing valid tokens will leave the connected account in an inconsistent state.

### Error responses

- **404 Not Found**: No connected account exists for the given user and slug.

## Upsert an API key for a connected account

Creates or updates an API-key-based installation for the specified integration, owned by the user or, when `connection_owner` is `organization`, shared by the organization. If an installation already exists, the stored API key is rotated to the new value. To create another connection, use POST.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/data-integrations/github/api-key" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "secret": "sk-1234567890abcdef"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.pipes.updateDataIntegrationApiKey({
  slug: 'github',
  userId: 'user_01EHZNVPK3SFK441A1RGBFSHRT',
  secret: 'sk-1234567890abcdef',
});
```

```rb language="ruby" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.update_data_integration_api_key(
  slug: "github",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  secret: "sk-1234567890abcdef"
)
```

```py language="python" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.update_data_integration_api_key(
    slug="github",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
    secret="sk-1234567890abcdef",
)
```

```go language="go" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().UpdateDataIntegrationAPIKey(context.Background(), "github", &workos.PipesUpdateDataIntegrationAPIKeyParams{
		UserID: "user_01EHZNVPK3SFK441A1RGBFSHRT",
		Secret: "sk-1234567890abcdef",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->updateDataIntegrationApiKey(
        slug: "github",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        secret: "sk-1234567890abcdef",
    );
```

```java language="java" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports
// optional-intent unions
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.UpdateDataIntegrationApiKeyOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateDataIntegrationApiKeyOptions options =
    UpdateDataIntegrationApiKeyOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .secret("sk-1234567890abcdef")
        .build();

workos.pipes.updateDataIntegrationApiKey("github", options);
```

```cs language="dotnet" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.UpdateDataIntegrationApiKeyAsync("github", new PipesUpdateDataIntegrationApiKeyOptions {
    UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
    Secret = "sk-1234567890abcdef",
});
```

```rust language="rust" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
use workos::Client;
use workos::pipes::UpdateDataIntegrationApiKeyParams;

#[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_api_key(
            "github",
            UpdateDataIntegrationApiKeyParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                secret: "sk-1234567890abcdef".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "scopes": [],
  "auth_method": "api_key",
  "api_key_last_4": "cdef",
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

## Upsert client credentials for a connected account

Creates or updates a client-credentials-based installation for the specified integration, owned by the user or, when `connection_owner` is `organization`, shared by the organization. If an installation already exists, the stored client credentials are rotated to the new values. To create another connection, use POST.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/data-integrations/salesforce/client-credentials" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
        "client_id": "3MVG9...",
        "client_secret": "shhh-secret"
    }
BODY
```

```rb language="ruby" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.pipes.update_data_integration_client_credentials(
  slug: "salesforce",
  user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT",
  client_id: "3MVG9...",
  client_secret: "shhh-secret"
)
```

```py language="python" title="Request" tab="1"
# workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.pipes.update_data_integration_client_credentials(
    slug="salesforce",
    user_id="user_01EHZNVPK3SFK441A1RGBFSHRT",
    client_id="3MVG9...",
    client_secret="shhh-secret",
)
```

```go language="go" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Pipes().UpdateDataIntegrationClientCredentials(context.Background(), "salesforce", &workos.PipesUpdateDataIntegrationClientCredentialsParams{
		UserID:       "user_01EHZNVPK3SFK441A1RGBFSHRT",
		ClientID:     "3MVG9...",
		ClientSecret: "shhh-secret",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->pipes()
    ->updateDataIntegrationClientCredentials(
        slug: "salesforce",
        userId: "user_01EHZNVPK3SFK441A1RGBFSHRT",
        clientId: "3MVG9...",
        clientSecret: "shhh-secret",
    );
```

```java language="java" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports
// optional-intent unions
import com.workos.WorkOS;
import com.workos.pipes.PipesApi.UpdateDataIntegrationClientCredentialsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

UpdateDataIntegrationClientCredentialsOptions options =
    UpdateDataIntegrationClientCredentialsOptions.builder()
        .userId("user_01EHZNVPK3SFK441A1RGBFSHRT")
        .clientId("3MVG9...")
        .clientSecret("shhh-secret")
        .build();

workos.pipes.updateDataIntegrationClientCredentials("salesforce", options);
```

```cs language="dotnet" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Pipes.UpdateDataIntegrationClientCredentialsAsync("salesforce",
                                                               new PipesUpdateDataIntegrationClientCredentialsOptions {
                                                                   UserId = "user_01EHZNVPK3SFK441A1RGBFSHRT",
                                                                   ClientId = "3MVG9...",
                                                                   ClientSecret = "shhh-secret",
                                                               });
```

```rust language="rust" title="Request" tab="1"
// workos:manual - preserve required legacy parameters until oagen supports optional-intent unions
use workos::Client;
use workos::pipes::UpdateDataIntegrationClientCredentialsParams;

#[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_client_credentials(
            "salesforce",
            UpdateDataIntegrationClientCredentialsParams {
                user_id: "user_01EHZNVPK3SFK441A1RGBFSHRT".into(),
                client_id: "3MVG9...".into(),
                client_secret: "shhh-secret".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "connected_account",
  "id": "data_installation_01EHZNVPK3SFK441A1RGBFSHRT",
  "connection_role": "compatibility",
  "account_identifier": "workspace_123",
  "account_display_name": "Acme production",
  "user_id": "user_01EHZNVPK3SFK441A1RGBFSHRT",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "scopes": [],
  "auth_method": "client_credentials",
  "state": "connected",
  "created_at": "2024-01-16T14:20:00.000Z",
  "updated_at": "2024-01-16T14:20:00.000Z"
}
```

:::

### data_integration

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "data_integration" | Yes | Distinguishes the Data Integration object. |
| `id` | string | Yes | 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. |
| `ownership` | "user" \| "organization" | Yes | Who owns the Data Integration: `user` when users connect their own accounts, `organization` when organizations connect. Fixed at creation. |
| `description` | string | No | 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. |
| `scopes` | string[] | No | 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. Empty for `api_key` and `client_credentials` integrations, which run no authorization redirect. |
| `auth_methods` | ("oauth" \| "api_key" \| "client_credentials")[] | Yes | How accounts authenticate with the provider for this Data Integration. |
| `credentials` | object | No | The integration-level OAuth app credentials. `null` for `api_key` and `client_credentials` integrations, which hold no integration-level credentials (secrets are installed per-tenant). |
| `installation` | object | No | The tenant installation created when an API key was supplied at creation time; `null` otherwise. Not populated on list/get responses. |
| `config` | object | Yes | Provider-specific config values set on the Data Integration (e.g. a Snowflake `account`), keyed by config field. Only fields the provider declares are accepted. |
| `custom_provider` | object | No | The OAuth definition when this is a custom provider; `null` for built-in providers. |
| `created_at` | string | Yes | An ISO 8601 timestamp. |
| `updated_at` | string | Yes | An ISO 8601 timestamp. |

### POST /data-integrations/{slug}/api-key

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique label. Omit to preserve an existing label; null clears it. Labels are never account identifiers. |
| `account_identifier` | string | No | A developer-attested provider account identifier, never inferred from a label or credential. Omit to preserve an existing identifier; null clears it. |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. Required when `connection_owner` is `organization`. |
| `connection_owner` | "user" \| "organization" | No | Whose connection to create or rotate. `user` (the default) addresses the connection owned by `user_id`. `organization` addresses the connection shared by every member of `organization_id`; `user_id` then identifies the member performing the request and must be an active member of the organization. |
| `secret` | string | Yes | The API key secret to store for this integration. |
| `connection_intent` | "add" | Yes | Must be `add`: this endpoint only creates another connection. The first connection for an owner shape fills the compatibility slot; later connections are standard. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The identifier of the integration. |
| `idempotency-key` | string | No | Makes retries of this explicit add return the connection the first attempt created instead of creating another. Reuse the same key for every retry of one request. A matching retry within 24 hours returns the existing connection; reusing the key for a different owner, integration, or authentication method, or after 24 hours while that connection exists, returns 409 `idempotency_key_conflict`. If that connection was deleted, the key creates a new one. Requests without a key are not retry-safe. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### POST /data-integrations/{slug}/client-credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique label. Omit to preserve an existing label; null clears it. Labels are never account identifiers. |
| `account_identifier` | string | No | A developer-attested provider account identifier, never inferred from a label or credential. Omit to preserve an existing identifier; null clears it. |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. Required when `connection_owner` is `organization`. |
| `connection_owner` | "user" \| "organization" | No | Whose connection to create or rotate. `user` (the default) addresses the connection owned by `user_id`. `organization` addresses the connection shared by every member of `organization_id`; `user_id` then identifies the member performing the request and must be an active member of the organization. |
| `client_id` | string | Yes | The OAuth client ID to store for this integration. |
| `client_secret` | string | Yes | The OAuth client secret to store for this integration. |
| `config` | object | No | Provider-specific configuration values collected for this installation, keyed by the provider's config field descriptors. |
| `connection_intent` | "add" | Yes | Must be `add`: this endpoint only creates another connection. The first connection for an owner shape fills the compatibility slot; later connections are standard. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The identifier of the integration. |
| `idempotency-key` | string | No | Makes retries of this explicit add return the connection the first attempt created instead of creating another. Reuse the same key for every retry of one request. A matching retry within 24 hours returns the existing connection; reusing the key for a different owner, integration, or authentication method, or after 24 hours while that connection exists, returns 409 `idempotency_key_conflict`. If that connection was deleted, the key creates a new one. Requests without a key are not retry-safe. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### POST /organizations/{organization_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique connection label; null clears it. Not an account identifier. |
| `account_identifier` | string | No | A developer-attested account identifier; null clears it. |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. Required when `access_token` is provided for tokens that expire. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the state is derived from the token combination provided. |
| `user_id` | string | Yes | The [User](/reference/authkit/user) identifier of the organization member on whose behalf the connected account is being imported or updated. The user must be an active member of the organization. |
| `connection_intent` | "add" | No | Set to `add` to create another connected account. Omit this field for permanent compatibility behavior. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | An [Organization](/reference/organization) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `idempotency-key` | string | No | Makes retries of this explicit add return the connection the first attempt created instead of creating another. Reuse the same key for every retry of one request. A matching retry within 24 hours returns the existing connection; reusing the key for a different owner, integration, or authentication method, or after 24 hours while that connection exists, returns 409 `idempotency_key_conflict`. If that connection was deleted, the key creates a new one. Requests without a key are not retry-safe. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### POST /user_management/users/{user_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique connection label; null clears it. Not an account identifier. |
| `account_identifier` | string | No | A developer-attested account identifier; null clears it. |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. Required when providing both `access_token` and `refresh_token` for tokens that expire. Providing `expires_at` with `access_token` but without `refresh_token` returns a `422` error. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the state is derived from the token combination provided. |
| `connection_intent` | "add" | No | Set to `add` to create another connected account. Omit this field for permanent compatibility behavior. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. |
| `idempotency-key` | string | No | Makes retries of this explicit add return the connection the first attempt created instead of creating another. Reuse the same key for every retry of one request. A matching retry within 24 hours returns the existing connection; reusing the key for a different owner, integration, or authentication method, or after 24 hours while that connection exists, returns 409 `idempotency_key_conflict`. If that connection was deleted, the key creates a new one. Requests without a key are not retry-safe. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### DELETE /organizations/{organization_id}/connected_accounts/{slug}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | An [Organization](/reference/organization) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `supports_multiple_connections` | boolean | No | Set to `true` to use the plural connection contract. When omitted or `false`, only the compatibility connection is considered. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select the connection to delete. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### DELETE /user_management/users/{user_id}/connected_accounts/{slug}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization. |
| `supports_multiple_connections` | boolean | No | Set to `true` to use the plural connection contract. When omitted or `false`, only the compatibility connection is considered. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select the connection to delete. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `empty` | empty | Returns an empty response on success. |

### POST /data-integrations/{slug}/authorize

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique label. Omit to preserve an existing label; null clears it. Labels are never account identifiers. |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. This is the user who will authorize the connection. |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. |
| `connection_owner` | "user" \| "organization" | No | Who will own the connected account. `user` (the default) connects the user's own account. `organization` connects the organization's shared account and requires `organization_id`. |
| `return_to` | string | No | The URL to redirect the user to after authorization. |
| `config` | object | No | Connect-time config values for the provider-declared `installation`-scope fields (e.g. a Zendesk `subdomain`), keyed by the config field. Only fields the provider declares may be supplied, and required fields must be provided unless already pinned on the integration. |
| `connection_intent` | "add" \| "reauthorize" | No | Create another connection. The first connection for an owner shape fills the compatibility slot; later connections are standard. Omit `connection_intent` to use the compatibility connection, or send `reauthorize` with `connected_account_id` to reauthorize one exact connection. |
| `connected_account_id` | string | No | The exact connected account to reauthorize. Required with `connection_intent: reauthorize`. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `url` | string | The OAuth authorization URL to redirect the user to. |

### GET /organizations/{organization_id}/connected_accounts/{slug}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | An [Organization](/reference/organization) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `supports_multiple_connections` | boolean | No | Set to `true` to use the plural connection contract. When omitted or `false`, only the compatibility connection is considered. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select a specific connection when the organization has several for this provider. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### GET /organizations/{organization_id}/data_providers

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | An [Organization](/reference/organization) identifier to list providers and connected accounts for. |
| `supports_multiple_connections` | boolean | No | Set to `true` to use the plural connection contract. When omitted or `false`, only the compatibility connection is considered. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `list` | object | Indicates this is a list response. |

### GET /user_management/users/{user_id}/connected_accounts/{slug}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter if the connection is scoped to an organization. |
| `supports_multiple_connections` | boolean | No | Set to `true` to use the plural connection contract. When omitted or `false`, only the compatibility connection is considered. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select a specific connection when the user has several for this provider. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### PUT /organizations/{organization_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique connection label; null clears it. Not an account identifier. |
| `account_identifier` | string | No | A developer-attested account identifier; null clears it. |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. Required when `access_token` is provided for tokens that expire. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the state is derived from the token combination provided. |
| `user_id` | string | Yes | The [User](/reference/authkit/user) identifier of the organization member on whose behalf the connected account is being imported or updated. The user must be an active member of the organization. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organization_id` | string | Yes | An [Organization](/reference/organization) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `supports_multiple_connections` | boolean | No | Accepted for compatibility; does not change update targeting. Omit intent and selector to update the compatibility connection, or supply `connected_account_id` to update an exact connection. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select the connection to update. |
| `connection_intent` | "reauthorize" | No | Set to `reauthorize` with `connected_account_id` to update one exact connection. The intent may be omitted when supplying an ID. Omit both for permanent compatibility behavior. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### PUT /user_management/users/{user_id}/connected_accounts/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique connection label; null clears it. Not an account identifier. |
| `account_identifier` | string | No | A developer-attested account identifier; null clears it. |
| `access_token` | string | No | The OAuth access token for the connected account. |
| `refresh_token` | string | No | The OAuth refresh token for the connected account. |
| `expires_at` | string | No | The ISO-8601 timestamp when the access token expires. |
| `scopes` | string[] | No | The OAuth scopes granted for this connection. |
| `state` | "connected" \| "needs_reauthorization" | No | Explicitly set the state of the connected account. When omitted, the existing state is preserved. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `slug` | string | Yes | The slug identifier of the provider (e.g., `github`, `slack`, `notion`). |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Required if the connected account is scoped to an organization. |
| `supports_multiple_connections` | boolean | No | Accepted for compatibility; does not change update targeting. Omit intent and selector to update the compatibility connection, or supply `connected_account_id` to update an exact connection. |
| `connected_account_id` | string | No | A [connected account](/reference/pipes/connected-account) identifier. Use this to select the connection to update. |
| `connection_intent` | "reauthorize" | No | Set to `reauthorize` with `connected_account_id` to update one exact connection. The intent may be omitted when supplying an ID. Omit both for permanent compatibility behavior. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### PUT /data-integrations/{slug}/api-key

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique label. Omit to preserve an existing label; null clears it. Labels are never account identifiers. |
| `account_identifier` | string | No | A developer-attested provider account identifier, never inferred from a label or credential. Omit to preserve an existing identifier; null clears it. |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. Required when `connection_owner` is `organization`. |
| `connection_owner` | "user" \| "organization" | No | Whose connection to create or rotate. `user` (the default) addresses the connection owned by `user_id`. `organization` addresses the connection shared by every member of `organization_id`; `user_id` then identifies the member performing the request and must be an active member of the organization. |
| `secret` | string | Yes | The API key secret to store for this integration. |
| `connection_intent` | "reauthorize" | No | Reauthorize exactly the connection named by `connected_account_id`. |
| `connected_account_id` | string | No | The exact connected account to reauthorize. Required with `connection_intent: reauthorize`. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The identifier of the integration. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |

### PUT /data-integrations/{slug}/client-credentials

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account_display_name` | string | No | A mutable, non-unique label. Omit to preserve an existing label; null clears it. Labels are never account identifiers. |
| `account_identifier` | string | No | A developer-attested provider account identifier, never inferred from a label or credential. Omit to preserve an existing identifier; null clears it. |
| `user_id` | string | Yes | A [User](/reference/authkit/user) identifier. |
| `organization_id` | string | No | An [Organization](/reference/organization) identifier. Optional parameter to scope the connection to a specific organization. Required when `connection_owner` is `organization`. |
| `connection_owner` | "user" \| "organization" | No | Whose connection to create or rotate. `user` (the default) addresses the connection owned by `user_id`. `organization` addresses the connection shared by every member of `organization_id`; `user_id` then identifies the member performing the request and must be an active member of the organization. |
| `client_id` | string | Yes | The OAuth client ID to store for this integration. |
| `client_secret` | string | Yes | The OAuth client secret to store for this integration. |
| `config` | object | No | Provider-specific configuration values collected for this installation, keyed by the provider's config field descriptors. |
| `connection_intent` | "reauthorize" | No | Reauthorize exactly the connection named by `connected_account_id`. |
| `connected_account_id` | string | No | The exact connected account to reauthorize. Required with `connection_intent: reauthorize`. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The identifier of the integration. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `connected_account` | object | Distinguishes the connected account object. |