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 downstream API and dynamically inserts your end user’s auth credentials
3. The proxy returns the response from the downstream API back to you

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.

• A Pipedream OAuth client to make authenticated requests to Pipedream’s API
• Connect environment (ex, production or development)
• The external user ID for your end user (ex, abc-123)
• The account ID for your end user’s connected account (ex, apn_1234567)

Refer to the full Connect API here.

Using the Pipedream SDK (preferred)

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_projectId},
  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!" // These get sent to the downstream API
      },
      body: {
        text: "hello, world",
        channel: "C03NA8B4VA9"
      },
    },
  }
)
 
// Parse and return the data you need
console.log(resp);

Using the REST API

You can also send a request to the Connect REST API with the below config:

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 an URL-safe Base64 encoded string (ex, aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U)

HTTP method

• Use the HTTP method required by the downstream API

Body

• Optionally include a body to send to the downstream 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 downstream API

# First, obtain an OAuth access token
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