iframe-proxy | Sunbelt Computer Software

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

You need code-level control and you want to use Pipedream’s OAuth instead of your own OAuth client
There isn’t a pre-built tool (action) for the app, or you need to modify the request
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.

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

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 one of the Pipedream SDKs or directly with the Pipedream REST API.

Prerequisites

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.

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 3,000+ 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

When making requests to the Connect Proxy, you must provide the following parameters: URL

The URL of the API you want to call (ex, https://slack.com/api/chat.postMessage)
If using the REST API directly, this should be a URL-safe Base64 encoded string (ex, aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U)

For apps with dynamic domains (like Zendesk, Zoho, GitLab), you should use relative paths in your proxy requests. Pipedream automatically resolves the correct domain based on the user’s connected account. See When to use relative vs full URLs for details.

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

Examples

import { PipedreamClient } from "@pipedream/sdk";
 
const client = new PipedreamClient({
  projectEnvironment: {development | production},
  projectId: {your_pipedream_project_id},
  clientId: {your_oauth_client_id},
  clientSecret: {your_oauth_client_secret}
});
 
 
const resp = await client.proxy.post(
  {
    externalUserId: "{external_user_id}", // The external user ID for your end user
    accountId: "{account_id}", // The account ID for your end user (ex, apn_1234567)
    url: "https://slack.com/api/chat.postMessage", // Include any query params you need; no need to Base64 encode the URL if using the SDK
    headers: {
      "x-pd-proxy-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);

from pipedream import Pipedream

pd = Pipedream(
    project_environment="{development | production}",
    project_id="{your_pipedream_project_id}",
    client_id="{your_oauth_client_id}",
    client_secret="{your_oauth_client_secret}"
)

response = pd.proxy.post(
    "https://slack.com/api/chat.postMessage",
    external_user_id="{external_user_id}",  # The external user ID for your end user
    account_id="{account_id}",  # The account ID for your end user (ex, apn_1234567)
    body={
        "text": "hello, world",
        "channel": "C03NA8B4VA9",
    },
    headers={
        "x-pd-proxy-hello": "world!"  # Include any headers you need to send to the upstream API
    }
)

# Parse and return the data you need
print(response)

import com.pipedream.api.PipedreamClient;
import com.pipedream.api.requests.ProxyPostRequest;
import com.pipedream.api.requests.RequestOptions;
import java.util.Map;

PipedreamClient client = PipedreamClient.builder()
    .projectEnvironment("{development | production}")
    .projectId("{your_pipedream_project_id}")
    .clientId("{your_oauth_client_id}")
    .clientSecret("{your_oauth_client_secret}")
    .build();

Map<String, Object> body = Map.of(
    "text", "hello, world",
    "channel", "C03NA8B4VA9"
);

ProxyPostRequest request = ProxyPostRequest.builder()
    .externalUserId("{external_user_id}")  // The external user ID for your end user
    .accountId("{account_id}")  // The account ID for your end user (ex, apn_1234567)
    .body(body)
    .build();

RequestOptions options = RequestOptions.builder()
    .addHeader("x-pd-proxy-hello", "world!")  // Include any headers you need to send to the upstream API
    .build();

Object response = client.proxy().post("https://slack.com/api/chat.postMessage", request, options);

// Parse and return the data you need
System.out.println(response);

# 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}" \
  -H "x-pd-proxy-hello: world" \
  -d '{
    "text": "hello, world",
    "channel": "C03NA8B4VA9"
  }'
 
# Parse and return the data you need

Allowed domains

The vast majority of apps in Pipedream work with the Connect Proxy. To check if an app is supported and what domains are allowed, use pd.getApps() or the /apps REST API.

Understanding the Connect object

Each app in the /apps API response includes a connect object:

{
  "id": "app_OkrhR1",
  "name_slug": "slack",
  "name": "Slack",
  // ...other fields...
  "connect": {
    "allowed_domains": [
      "slack.com"
    ],
    "base_proxy_target_url": "https://slack.com",
    "proxy_enabled": true
  }
}

{
  "id": "app_1Z2hw1",
  "name_slug": "gitlab",
  "name": "GitLab",
  // ...other fields...
  "connect": {
    "allowed_domains": [
      "gitlab.com"
    ],
    "base_proxy_target_url": "https://{{custom_fields.base_api_url}}",
    "proxy_enabled": true
  }
}

Field	Description
`proxy_enabled`	Whether the app supports the Connect Proxy
`allowed_domains`	Domains you can send requests to when using full URLs
`base_proxy_target_url`	The base URL for proxy requests, may contain placeholders for account-specific values

When to use relative vs full URLs

The format of base_proxy_target_url determines whether you should use a relative path or full URL:

Apps with static domains

If base_proxy_target_url is a standard URL (e.g., https://slack.com), you can use either:

Full URL: https://slack.com/api/chat.postMessage
Relative path: /api/chat.postMessage

Apps with dynamic domains

If base_proxy_target_url contains placeholders like {{custom_fields.base_api_url}}, you must use relative paths. This applies to:

Self-hosted instances (GitLab)
Apps with account-specific subdomains (Zendesk, Zoho)

For these apps, Pipedream resolves the actual domain from the user’s connected account at runtime.

Examples

// Both work
await client.proxy.post({
  externalUserId: "user-123",
  accountId: "apn_1234567",
  url: "https://slack.com/api/chat.postMessage",
  body: {...}
})
 
await client.proxy.post({
  accountId: "apn_1234567",
  externalUserId: "user-123",
  url: "/api/chat.postMessage",
  body: {...}
})

// Must use relative path
await client.proxy.get({
  accountId: "apn_1234567",
  externalUserId: "user-123",
  url: "/api/v4/projects",  // Pipedream resolves to the end user's GitLab instance
})

Discovering app support programmatically

const apps = await client.apps.list()
 
// Filter for apps that support the proxy
const proxyEnabledApps = apps.filter(app => app.connect?.proxy_enabled)

curl https://api.pipedream.com/v1/apps \
  -H "Authorization: Bearer <token>"

Refer to the Connect API Reference to learn more about listing apps.

Limits

The maximum timeout for a request is 30 seconds. Requests that take longer than 30 seconds will be terminated, and Pipedream will return a 504 error to the caller.

Restricted headers

The following headers are not allowed when making requests through the Connect API Proxy. Requests that include these headers will be rejected with a 400 error:

Accept-Encoding
Access-Control-Request-Headers
Access-Control-Request-Method
Connection
Content-Length
Cookie
Date
DNT
Expect
Host
Keep-Alive
Origin
Permissions-Policy
Referer
TE
Trailer
Transfer-Encoding
Upgrade
Via
Headers starting with Proxy-
Headers starting with Sec-

Sunbelt Computer Software

PL/B Language Development and Support

Getting Started

Connect

Workflows

Platform

Additional Resources

Connect API Proxy

Overview

Getting started

Prerequisites

Authenticating on behalf of your users

Sending requests

Examples

Allowed domains

Understanding the Connect object

When to use relative vs full URLs

Apps with static domains

Apps with dynamic domains

Examples

Discovering app support programmatically

Limits

Restricted headers

Sunbelt Computer Software

PL/B Language Development and Support

​Overview

​Getting started

​Prerequisites

​Authenticating on behalf of your users

​Sending requests

​Examples

​Allowed domains

​Understanding the Connect object

​When to use relative vs full URLs

​Apps with static domains

​Apps with dynamic domains

​Examples

​Discovering app support programmatically

​Limits

​Restricted headers

Overview

Getting started

Prerequisites

Authenticating on behalf of your users

Sending requests

Examples

Allowed domains

Understanding the Connect object

When to use relative vs full URLs

Apps with static domains

Apps with dynamic domains

Examples

Discovering app support programmatically

Limits

Restricted headers