ConnectAPI proxy

Connect API Proxy

Pipedream Connect provides a proxy API that you can use to send authenticated requests to any integrated API on behalf of your users, which is useful in a few scenarios:

  1. You need code-level control and you want to use Pipedream’s OAuth instead of your own OAuth client
  2. There isn’t a pre-built tool (action) for the app, or you need to modify the request
  3. You want to avoid storing end user credentials in your app

Overview

The Connect proxy enables you to interface with any integrated API and make authenticated requests on behalf of your users, without dealing with OAuth or storing end user credentials.

  1. You send a request to the proxy and identify the end user you want to act on behalf of
  2. The proxy sends the request to the upstream API and dynamically inserts your end user’s auth credentials
  3. The proxy returns the response from the upstream API back to you

Connect API proxy visualization

Before getting started with the Connect proxy, make sure you’ve already gone through the managed auth quickstart for Pipedream Connect.

Getting started

You can send requests to the Connect proxy using the Pipedream SDK with a fetch-style interface, or by making a request to the REST API.

Refer to the full Connect API here.

Authenticating on behalf of your users

One of the core benefits of using the Connect API Proxy is not having to deal with storing or retrieving sensitive credentials for your end users.

Since Pipedream has 2,500+ integrated apps, we know how the upstream APIs are expecting to receive access tokens or API keys. When you send a request to the proxy, Pipedream will look up the corresponding connected account for the relevant user, and automatically insert the authorization credentials in the appropriate header or URL param.

Sending requests

URL

  • The URL of the API you want to call (ex, https://slack.com/api/chat.postMessage)
  • When using the REST API, this should be a URL-safe Base64 encoded string (ex, aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U)
  • Some APIs like Zendesk, Zoho, and others use dynamic base domains that are account-specific (e.g, https://foo.zendesk.com). For any of these apps, you should pass a relative path as the url in your proxy request, like /api/v2/chat/chats for example.
  • Those dynamic fields are typically defined by the end user during the account connection flow, so the domain value will be stored as part of their connected account credentials in Pipedream.

HTTP method

  • Use the HTTP method required by the upstream API

Body

  • Optionally include a body to send to the upstream API

Headers

  • If using the REST API, include the Authorization header with your Pipedream OAuth access token (Bearer {access_token})
  • Headers that contain the prefix x-pd-proxy will get forwarded to the upstream API

Using the Pipedream SDK

You can use the Pipedream SDK to send a fetch-style request:

import { createBackendClient } from "@pipedream/sdk/server";
 
const pd = createBackendClient({
  environment: {development | production},
  projectId: {your_pipedream_project_i_d},
  credentials: {
    clientId: {your_oauth_client_id},
    clientSecret: {your_oauth_client_secret}
  },
});
 
 
const resp = await pd.makeProxyRequest(
  {
    searchParams: {
      account_id: "{account_id}", // The account ID for your end user (ex, apn_1234567)
      external_user_id: "{external_user_id}", // The external user ID for your end user
    }
  },
  {
    url: "https://slack.com/api/chat.postMessage", // Include any query params you need; no need to Base64 encode the URL if using the SDK
    options: {
      method: "POST",
      headers: {
        hello: "world!" // Include any headers you need to send to the upstream API
      },
      body: {
        text: "hello, world",
        channel: "C03NA8B4VA9"
      },
    },
  }
)
 
// Parse and return the data you need
console.log(resp);

Using the REST API

You can also use the Connect REST API directly. If using the REST API, send your Pipedream OAuth access token in the Authorization header:

# First, obtain an OAuth access token to authenticate to the Pipedream API
 
curl -X POST https://api.pipedream.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "{your_oauth_client_id}",
    "client_secret": "{your_oauth_client_secret}"
  }'
 
# The response will include an access_token. Use it in the Authorization header below.
 
curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/proxy/{url_safe_base64_encoded_url}?external_user_id={external_user_id}&account_id={apn_xxxxxxx}" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-pd-environment: {development | production}" \
  -d '{
    "text": "hello, world",
    "channel": "C03NA8B4VA9"
  }'
 
# Parse and return the data you need

Limits

The Connect proxy limits API requests to,

  • 100 requests per minute per project. Requests that surpass this limit will receive a 429 response.
  • A maximum timeout of 30 seconds. Requests that take longer than 30 seconds will be terminated, and Pipedream will return a 504 error to the caller.
  • Please let us know if you need higher limits.
Pre-built toolsWorkflows