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

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

#### Request

#### Response

> **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 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.

#### Request

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

#### Request

#### Response

## Get a connected account

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

#### Request

#### Response

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

#### Request

#### Response

> **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 and user. If an installation already exists, the stored API key is rotated to the new value.

#### Request

#### Response

### 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. |
| `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. |
| `credentials` | object | Yes | The credentials configured for the Data Integration. |
| `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 /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 to scope the connection to a specific organization. |

#### Returns

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

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

#### Returns

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

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

#### 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 /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. |

#### Returns

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

### PUT /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. Required if the connected account is scoped to an organization. |

#### Returns

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

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

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