> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.

# Pipedream Integration Guide

![Pipedream Integration](/_fern-img/668f23a0743d3c3946b874a2ab2051e9a1fb432bdbae93f8422f1ac881fe5362.webp)

## Overview

Pipedream enables workflow automation with 2,000+ integrated apps. Airweave can leverage your existing Pipedream connections to sync data without requiring users to authenticate again.

This integration involves two separate OAuth clients:

1. **Pipedream OAuth client**: Allows Airweave to access Pipedream's API
2. **Source app OAuth clients**: Custom OAuth clients you create for each source app (Notion, Google Drive, etc.)

> **Note**
>
> **Important**: Pipedream only exposes credentials for accounts created with your own custom OAuth clients. Default Pipedream OAuth connections use the Proxy API.

## Prerequisites

### For Pipedream API access:

* A Pipedream account with API access
* Pipedream OAuth client credentials (for Airweave to Pipedream authentication)

### For source app access:

* Custom OAuth clients created in each source app (Notion, Google Drive, etc.)
* Source app accounts connected to Pipedream using your custom OAuth clients
* Not accounts connected using Pipedream's default OAuth implementations

## Setup Guide

#### Set up Pipedream OAuth client

First, configure the OAuth client that allows Airweave to access Pipedream's API:

1. Log in to [Pipedream](https://pipedream.com)
2. Navigate to your Project Settings
3. Create a new OAuth client for Airweave integration
4. Configure redirect URIs if required
5. Save your `client_id` and `client_secret`

> **Note**
>
> **Purpose**: This OAuth client enables Airweave to authenticate with Pipedream's API to retrieve your connected account credentials.

#### Connect Pipedream to Airweave

1. Go to [Airweave Auth Providers](https://app.airweave.ai/auth-providers)
2. Click "Connect" next to Pipedream
3. Enter your Pipedream OAuth client credentials:
   * `client_id` (from step 1)
   * `client_secret` (from step 1)
4. Provide a readable name for this connection
5. Click "Save"

#### Create custom OAuth clients for source apps

For each source app you want to sync (Notion, Google Drive, etc.), you must create custom OAuth clients:

#### For Notion

1. Go to [Notion Developers](https://developers.notion.com)
2. Create a new integration
3. Configure OAuth settings with your redirect URIs
4. Save the `client_id` and `client_secret`

#### For Other Apps:

Follow similar steps for Google Drive, GitHub, or other source integrations.

> **Note**
>
> **Important**: You must use these custom OAuth clients when connecting accounts in Pipedream. Do not use Pipedream's built-in OAuth options.

#### Connect source apps in Pipedream using custom OAuth

1. In Pipedream, go to your project's connections
2. For each source app (Notion, Google Drive, etc.):
   * Choose "Custom OAuth" option
   * Enter your custom OAuth client credentials from Step 3
   * Complete the OAuth flow to connect your account
3. Note the `account_id` for each connection (format: `apn_xxxxx`)

#### Find your connection details

To create source connections, you'll need these identifiers:

1. `project_id`: Found in the URL when viewing your project (e.g., `proj_JPsD74a`)
2. `account_id`: Retrieved via Pipedream UI or API
3. `external_user_id`: Retrieved via Pipedream UI or API

```bash
curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts?include_credentials=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

The response will include account IDs like `apn_gyha5Ky`.

#### Create Source Connections

Create source connections that automatically retrieve credentials from Pipedream:

**`Python`**

```python title="Python"
from airweave import AirweaveSDK

client = AirweaveSDK(api_key="YOUR_API_KEY")

# Create a Notion connection using Pipedream credentials
source_connection = client.source_connections.create(
    name="Company Notion Workspace",
    short_name="notion",
    authentication={
        "provider_readable_id": "my-pipedream-connection-xyz789",  # Your Pipedream connection ID
        "provider_config": {
            "project_id": "proj_JPsD74a",      # From Pipedream
            "account_id": "apn_gyha5Ky",       # From Pipedream API
            "external_user_id": "user123",     # Required: unique user identifier
            "environment": "production",        # Optional, defaults to "production"
        }
    }
)

print(f"Created: {source_connection.name}")
```

**`TypeScript`**

```typescript title="TypeScript"
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({
  apiKey: "YOUR_API_KEY"
});

// Create a Notion connection using Pipedream credentials
const sourceConnection = await client.sourceConnections.create({
  name: "Company Notion Workspace",
  shortName: "notion",
  authentication: {
    providerReadableId: "my-pipedream-connection-xyz789",  // Your Pipedream connection ID
    providerConfig: {
      project_id: "proj_JPsD74a",      // From Pipedream
      account_id: "apn_gyha5Ky",       // From Pipedream API
      external_user_id: "user123",     // Required: unique user identifier
      environment: "production",      // Optional, defaults to "production"
    }
  }
});

console.log(`Created: ${sourceConnection.name}`);
```

**`cURL`**

```bash title="cURL"
curl -X POST 'https://app.airweave.ai/source-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Company Notion Workspace",
  "short_name": "notion",
  "authentication": {
    "provider_readable_id": "my-pipedream-connection-xyz789",
    "provider_config": {
      "project_id": "proj_JPsD74a",
      "account_id": "apn_gyha5Ky",
      "environment": "production",
      "external_user_id": "user123"
    }
  }
}'
```

> **Note**
>
> **Note**: API Validation
>
> The API now performs validation on auth provider source connections:
>
> 1. **Provider Existence**: 404 error if the specified `provider_readable_id` doesn't exist
> 2. **Source Compatibility**: 400 error if the provider doesn't support the specified source
>
> **Example error response when provider doesn't support a source:**
>
> ```json
> {
>   "detail": "Source 'github' does not support 'pipedream' as an auth provider. Supported providers: []"
> }
> ```

## How It Works

The integration uses two distinct OAuth flows:

### OAuth flow overview

1. **Airweave to Pipedream**: Uses your Pipedream OAuth client for API access
2. **Pipedream to source apps**: Uses your custom OAuth clients for each source app

```mermaid
sequenceDiagram
    participant You
    participant Airweave
    participant Pipedream
    participant Notion

    Note over You,Notion: Setup Phase (Two OAuth clients)
    You->>Notion: Create custom OAuth client
    Note over You,Notion: client_id: "notion_abc123"<br />client_secret: "notion_secret"
    You->>Pipedream: Connect Notion with your OAuth client
    Note over You,Pipedream: Uses notion_abc123, not Pipedream's default
    Pipedream-->>You: project_id: "proj_JPsD74a"<br />account_id: "apn_gyha5Ky"

    Note over You,Notion: Configure Airweave
    You->>Airweave: Configure Pipedream auth provider
    Note over You,Airweave: Uses your Pipedream OAuth client
    You->>Airweave: POST /source-connections
    Note over You,Airweave: provider_readable_id: "pipedream-prod-xyz789"<br />project_id: "proj_JPsD74a"<br />account_id: "apn_gyha5Ky"

    Note over You,Notion: Sync data (Runtime)
    You->>Airweave: Trigger sync
    Airweave->>Pipedream: POST /oauth/token
    Note over Airweave,Pipedream: Uses your Pipedream OAuth client
    Pipedream-->>Airweave: Access token (1hr expiry)
    Airweave->>Pipedream: GET /connect/proj_JPsD74a/accounts/apn_gyha5Ky
    Note over Airweave,Pipedream: include_credentials=true
    Pipedream-->>Airweave: Notion OAuth credentials
    Note over Pipedream,Airweave: Returns your custom OAuth tokens
    Airweave->>Notion: Sync with credentials
    Notion-->>Airweave: Pages & databases
    Airweave-->>You: ✓ Sync complete
```

## Field Mappings

Pipedream uses different field names for some credentials:

| Airweave Field  | Pipedream Field       |
| --------------- | --------------------- |
| `access_token`  | `oauth_access_token`  |
| `refresh_token` | `oauth_refresh_token` |
| `client_id`     | `oauth_client_id`     |
| `client_secret` | `oauth_client_secret` |
| `api_key`       | `api_key`             |

These mappings are handled automatically.

## Token Management

Pipedream OAuth tokens have specific characteristics:

* **Expiry**: Access tokens expire after 3600 seconds (1 hour)
* **Auto-refresh**: Airweave refreshes tokens 5 minutes before expiry
* **Concurrency**: Token refresh is thread-safe with async locks
* **Grant Type**: Uses `client_credentials` flow

## Proxy Authentication

When you connect accounts using Pipedream's default OAuth clients, credentials aren't directly exposed for security reasons. Instead, Airweave automatically routes API requests through [Pipedream's proxy endpoint](https://pipedream.com/docs/connect/api-proxy), where the actual credentials are injected server-side. This happens transparently - sources continue using the same HTTP client interface whether they're accessing credentials directly (custom OAuth) or through the proxy (default OAuth). The system automatically detects which mode to use based on the OAuth client type, ensuring your data syncs work seamlessly regardless of how the account was connected in Pipedream.

## Troubleshooting

### `Credentials not available`

```
Detail: Credentials not available. Pipedream only exposes credentials for
accounts created with custom OAuth clients, not default Pipedream OAuth.
```

**Root cause**: The account was connected using Pipedream's built-in OAuth client instead of your custom OAuth client.

**Solution**:

1. Disconnect the account in Pipedream
2. Reconnect using "Custom OAuth" option with your own OAuth client credentials
3. Ensure you're using the OAuth client you created in the source app (e.g., Notion Developer Portal)

### `Account app mismatch`

```
Detail: Account apn_xxx is not for app 'notion'
```

**Solution**: Verify the `account_id` corresponds to the correct integration type and was created with the right custom OAuth client.

### `Failed to refresh token` (Airweave to Pipedream)

This affects the connection between Airweave and Pipedream's API:

* Check if your Pipedream OAuth client credentials are valid
* Ensure your Pipedream OAuth client is active
* Verify network connectivity to Pipedream API

### `Failed to refresh token` (Source App Authentication)

This affects the source app tokens retrieved from Pipedream:

* Verify your source app OAuth client (e.g., Notion, Google Drive) is still active
* Check if the source app tokens have been revoked
* Ensure the source app OAuth client has required permissions

### `Missing required auth fields`

* The integration may require fields not provided by your custom OAuth implementation
* Check the field mappings table above
* Verify the source app OAuth client has all required scopes
* Ensure your custom OAuth client configuration matches the source app's requirements

## API Reference

### Create source connection

**`Python`**

```python title="Python"
from airweave import AirweaveSDK

client = AirweaveSDK(api_key="YOUR_API_KEY")

source_connection = client.source_connections.create(
    name="Team Notion",
    short_name="notion",
    provider_readable_id="pipedream-connection-id",
    provider_config={
        "project_id": "proj_JPsD74a",
        "account_id": "apn_gyha5Ky",
        "external_user_id": "user123",
        "environment": "production"         # Optional, defaults to "production"
    }
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { AirweaveSDKClient } from "@airweave/sdk";

const client = new AirweaveSDKClient({
  apiKey: "YOUR_API_KEY"
});

const sourceConnection = await client.sourceConnections.create({
  name: "Team Notion",
  shortName: "notion",
  providerReadableId: "pipedream-connection-id",
  providerConfig: {
    projectId: "proj_JPsD74a",
    accountId: "apn_gyha5Ky",
    externalUserId: "user123",
    environment: "production"      // Optional, defaults to "production"
  }
});
```

**`cURL`**

```bash title="cURL"
curl -X POST 'https://app.airweave.ai/source-connections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Team Notion",
  "short_name": "notion",
  "provider_readable_id": "pipedream-connection-id",
  "provider_config": {
    "project_id": "proj_JPsD74a",
    "account_id": "apn_gyha5Ky",
    "external_user_id": "user123",
    "environment": "production"
  }
}'
```

## Limitations

1. **Dual OAuth setup required**: You need to create and manage two separate OAuth clients:
   * One for Pipedream API access (Airweave to Pipedream)
   * One for each source app (Pipedream to Notion/Asana/etc.)

2. **Custom OAuth clients only**:
   * Source app connections must use your own OAuth clients
   * Pipedream's built-in OAuth implementations are not supported
   * Cannot reuse existing accounts connected via Pipedream's default OAuth

3. **Token management complexity**:
   * Pipedream API tokens expire hourly, requiring automatic refresh
   * Source app tokens managed separately through Pipedream
   * Multiple token refresh flows to maintain

4. **API rate limits**: Subject to both Pipedream's API limits and source app limits

5. **Credential access**: Only available with `include_credentials=true` parameter and proper OAuth client setup

## Next Steps

* [Browse available sources](/sources)
* [Set up your first sync](/quickstart)
* [Learn about workflow automation](/concepts#workflows)