Pipedream Connect Implementation Guide

Pipedream Connect allows you to embed OAuth and API key authentication flows into your application, enabling your users to connect their accounts from thousands of integrated apps.

• A unique identifier from YOUR system that identifies each user
• Used to associate connected accounts with your users
• Must be consistent across all API calls for the same user

• Short-lived, one-time use token for secure authentication
• Generated server-side using your Pipedream credentials
• Valid for a limited time (check expires_at)

• Apps: Services like Google Sheets, Slack, etc. (identified by name_slug)
• Components: Pre-built actions (e.g., "add row to sheet") and triggers
• Components are identified by keys like google_sheets-add-single-row

PIPEDREAM_CLIENT_ID=your_client_id
PIPEDREAM_CLIENT_SECRET=your_client_secret
PIPEDREAM_PROJECT_ID=your_project_id
PIPEDREAM_PROJECT_ENVIRONMENT=development # or production
PIPEDREAM_API_HOST=api.pipedream.com # optional

Create val
import { createBackendClient } from "@pipedream/sdk/server"

const backendClient = createBackendClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID,
  environment: process.env.PIPEDREAM_PROJECT_ENVIRONMENT,
  credentials: {
    clientId: process.env.PIPEDREAM_CLIENT_ID,
    clientSecret: process.env.PIPEDREAM_CLIENT_SECRET,
  },
  apiHost: process.env.PIPEDREAM_API_HOST, // optional
})

Create val
const tokenResponse = await backendClient.createConnectToken({
  external_user_id: "user-123", // Your user's ID
  allowed_origins: ["https://yourdomain.com"], // For CORS (optional)
  webhook_uri: "https://yourdomain.com/webhooks", // For triggers (optional)
})

// Returns:
{
  token: "connect_token_xxx",
  connect_link_url: "https://connect.pipedream.com/connect?token=xxx",
  expires_at: "2024-01-01T00:00:00Z"
}

Create val
const accounts = await backendClient.getAccounts({
  external_user_id: "user-123",
  include_credentials: false, // Set true to get OAuth tokens (server-side only!)
})

// Returns array of connected accounts with app info

Create val
const account = await backendClient.getAccountById("account_id", {
  include_credentials: true // Gets OAuth tokens for making API calls
})

Create val
const appInfo = await backendClient.app("google_sheets")
// Returns app details including auth_type, name, etc.

Create val
const result = await backendClient.actionRun({
  userId: "user-123",
  actionId: "google_sheets-add-single-row",
  configuredProps: {
    drive: "drive_id",
    spreadsheet: "spreadsheet_id",
    worksheet: "worksheet_id",
    row: { "Column1": "Value1", "Column2": "Value2" }
  },
  dynamicPropsId: "optional_id" // For dynamic form fields
})

Create val
const trigger = await backendClient.deployTrigger({
  userId: "user-123",
  triggerId: "slack-new-message",
  configuredProps: {
    channel: "channel_id"
  },
  webhookUrl: "https://yourdomain.com/webhook/receive",
  dynamicPropsId: "optional_id"
})

No JavaScript required - just redirect users to the connect URL:

Create val
// Server-side: Generate token and get connect_link_url
const { connect_link_url } = await backendClient.createConnectToken({
  external_user_id: "user-123"
})

// Add app parameter to the URL
const fullConnectUrl = `${connect_link_url}&app=google_sheets`

// For custom OAuth clients, add:
const urlWithOAuth = `${fullConnectUrl}&oauthAppId=oa_xxxxx`

// Redirect user to this URL

Create val
import { createFrontendClient } from "@pipedream/sdk/browser"

// Initialize client
const frontendClient = createFrontendClient({
  environment: "development", // or "production"
  externalUserId: "user-123",
  tokenCallback: async (opts) => {
    // Fetch token from your backend
    const response = await fetch("/api/pipedream/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ 
        externalUserId: opts.externalUserId 
      })
    })
    return response.json()
  }
})

// Connect an account (opens iframe)
frontendClient.connectAccount({
  app: "google_sheets",
  token: "connect_token_xxx", // From your backend
  oauthAppId: "oa_xxxxx", // Optional: custom OAuth client
  onSuccess: ({ id }) => {
    console.log("Account connected:", id)
    // Save account ID, refresh account list, etc.
  }
})

Create val
import { 
  FrontendClientProvider, 
  ComponentForm,
  SelectApp,
  SelectComponent 
} from "@pipedream/connect-react"

// Wrap your app
<FrontendClientProvider client={frontendClient}>
  {/* Select an app */}
  <SelectApp 
    value={selectedApp}
    onChange={(app) => setSelectedApp(app)}
  />
  
  {/* Select a component (action/trigger) */}
  <SelectComponent
    app={selectedApp}
    componentType="action" // or "trigger"
    value={selectedComponent}
    onChange={(comp) => setSelectedComponent(comp)}
  />
  
  {/* Render dynamic form for component */}
  <ComponentForm
    userId="user-123"
    component={selectedComponent}
    onSubmit={async (configuredProps) => {
      // Execute the action
      const result = await frontendClient.actionRun({
        userId: "user-123",
        actionId: selectedComponent.key,
        configuredProps
      })
    }}
  />
</FrontendClientProvider>

Once users have connected their accounts, you can make API requests on their behalf:

Create val
// 1. Get account with credentials (server-side only!)
const account = await backendClient.getAccountById("account_id", {
  include_credentials: true
})

// 2. For OAuth apps:
const headers = {
  'Authorization': `Bearer ${account.credentials.oauth_access_token}`
}

// 3. For Basic Auth apps:
const username = account.credentials.username // Field names vary by app
const password = account.credentials.password
const basicAuth = Buffer.from(`${username}:${password}`).toString('base64')
const headers = {
  'Authorization': `Basic ${basicAuth}`
}

// 4. Make your API request
const response = await fetch("https://api.example.com/endpoint", {
  headers
})

When deploying triggers, Pipedream will send events to your webhook URL:

Create val
// Your webhook endpoint
app.post('/webhooks/pipedream', (req, res) => {
  const event = req.body
  
  // Event structure:
  {
    trigger_id: "trigger_deployment_id",
    event: {
      // Event-specific data
    },
    metadata: {
      // Additional context
    }
  }
  
  // Process the event
  processEvent(event)
  
  res.status(200).send('OK')
})

Components have configurable properties that can be:

• Required or optional
• Different types: string, integer, boolean, array, object, app (for account selection)
• Dynamic: Some props depend on values of other props

Example component configuration:

Create val
{
  drive: "drive_id",        // App account reference
  spreadsheet: "sheet_id",  // Dynamic: loaded based on drive
  worksheet: "worksheet_id", // Dynamic: loaded based on spreadsheet
  row: {                    // Object with column values
    "Name": "John Doe",
    "Email": "john@example.com"
  }
}

1. Generate external user ID (or use existing user ID)
2. Create connect token server-side
3. User connects account via Connect Link or embedded SDK
4. List user's connected accounts
5. Select a component (action/trigger)
6. Configure component properties
7. Execute action or deploy trigger
8. Handle results/events

This implementation pattern allows you to integrate thousands of apps into your platform while Pipedream handles the authentication, API complexity, and infrastructure.