Skip to content

Commit 3360f24

Browse files
dannyrooseveltdannyroosevelt
authored
Danny/connect proxy docs (#15476)
* first commit [draft] * checking work in; need to add redirects for dir changes * pnpm-lock * More progress, still WIP * More docs progress * Adding redirects to handle directory changes * Fixing broken link refs * Fixing more broken links * Adding some links * small update to environments page * Fixing bad link * Adding a couple visuals * pnpm-lock * more pnpm-lock * Updating API doc for proxy * More updates * connect proxy title * Adding ref to demo app * pnpm-lock * tweaking language for connect-react sdk
1 parent 185425d commit 3360f24

21 files changed

+243
-88
lines changed

‎docs-v2/next.config.mjs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ export default withNextra({
5050
TMP_SIZE_LIMIT: "2GB",
5151
DELAY_MIN_MAX_TIME:
5252
"You can pause your workflow for as little as one millisecond, or as long as one year",
53-
PUBLIC_APPS: "2,400",
53+
PUBLIC_APPS: "2,500",
5454
REGISTRY_ACTIONS: "5,300",
5555
REGISTRY_SOURCES: "2,500",
5656
REGISTRY_COMPONENTS: "8,000",

‎docs-v2/pages/_meta.tsx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ export default {
55
"projects": "Projects",
66
"workflows": "Workflows",
77
"connect": {
8-
title: "Pipedream Connect",
8+
title: "Connect",
99
},
1010
"code": "Code",
1111
"data-stores": "Data Stores",

‎docs-v2/pages/connect/_meta.tsx

Lines changed: 8 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -5,35 +5,23 @@ export default {
55
"use-cases": {
66
"title": "Use cases",
77
},
8-
"quickstart": {
8+
"managed-auth": {
99
"title": "Managed auth",
1010
},
11-
"workflows": {
12-
"title": "Running workflows",
13-
},
1411
"components": {
15-
"title": "Embedding components",
12+
"title": "Pre-built tools",
1613
},
17-
"api": {
18-
"title": "API & SDK reference",
14+
"api-proxy": {
15+
"title": "API proxy",
1916
},
20-
"tokens": {
21-
"title": "Connect tokens",
17+
"workflows": {
18+
"title": "Workflows",
2219
},
2320
"environments": {
2421
"title": "Environments",
2522
},
26-
"oauth-clients": {
27-
"title": "OAuth clients",
28-
},
29-
"webhooks": {
30-
"title": "Webhooks",
31-
},
32-
"connect-link": {
33-
"title": "Connect Link",
34-
},
35-
"customize-your-app": {
36-
"title": "Customize your app",
23+
"api": {
24+
"title": "API & SDK reference",
3725
},
3826
"troubleshooting": {
3927
"title": "Troubleshooting",

‎docs-v2/pages/connect/api-proxy.mdx

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
import { Tabs } from 'nextra/components'
2+
import Callout from '@/components/Callout'
3+
4+
# Connect API Proxy
5+
6+
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:
7+
8+
1. You need code-level control and you want to use [Pipedream's OAuth](/connect/managed-auth/oauth-clients#using-pipedream-oauth) instead of [your own OAuth client](/connect/managed-auth/oauth-clients#using-a-custom-oauth-client)
9+
2. There isn't a [pre-built tool](/connect/components) (action) for the app, or you need to modify the request
10+
3. You want to avoid storing end user credentials in your app
11+
12+
## Overview
13+
14+
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.
15+
16+
1. You send a request to the proxy and identify the end user you want to act on behalf of
17+
2. The proxy sends the request to the downstream API and dynamically inserts your end user's auth credentials
18+
3. The proxy returns the response from the downstream API back to you
19+
20+
![Connect API proxy visualization](https://res.cloudinary.com/pipedreamin/image/upload/v1738822030/pd-connect-proxy-viz_k5iksb.png)
21+
22+
<Callout type="info">
23+
Before getting started with the Connect proxy, make sure you've already gone through the [managed auth quickstart](/connect/managed-auth/quickstart) for Pipedream Connect.
24+
</Callout>
25+
26+
## Getting started
27+
28+
You can send requests to the Connect proxy using the [Pipedream SDK](/connect/sdk) with a fetch-style interface, or by making a request to the [REST API](/rest-api/connect/proxy).
29+
30+
- A [Pipedream OAuth client](/rest-api/auth#oauth) to make authenticated requests to Pipedream's API
31+
- Connect [environment](/connect/environments) (ex, `production` or `development`)
32+
- The [external user ID](/connect/api#external-users) for your end user (ex, `abc-123`)
33+
- The [account ID](/connect/api#accounts) for your end user's connected account (ex, `apn_1234567`)
34+
35+
Refer to the full Connect API [here](/connect/api).
36+
37+
### Using the Pipedream SDK (preferred)
38+
39+
You can use the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) to send a fetch-style request:
40+
41+
```javascript
42+
import { createBackendClient } from "@pipedream/sdk/server";
43+
44+
const pd = createBackendClient({
45+
environment: {development | production},
46+
projectId: {your_projectId},
47+
credentials: {
48+
clientId: {your_oauth_client_id},
49+
clientSecret: {your_oauth_client_secret}
50+
},
51+
});
52+
53+
54+
const resp = await pd.makeProxyRequest(
55+
{
56+
searchParams: {
57+
account_id: "{account_id}", // The account ID for your end user (ex, apn_1234567)
58+
external_user_id: "{external_user_id}", // The external user ID for your end user
59+
}
60+
},
61+
{
62+
url: "https://slack.com/api/chat.postMessage", // Include any query params you need; no need to Base64 encode the URL if using the SDK
63+
options: {
64+
method: "POST",
65+
headers: {
66+
hello: "world!" // These get sent to the downstream API
67+
},
68+
body: {
69+
text: "hello, world",
70+
channel: "C03NA8B4VA9"
71+
},
72+
},
73+
}
74+
)
75+
76+
// Parse and return the data you need
77+
console.log(resp);
78+
```
79+
80+
### Using the REST API
81+
82+
You can also send a request to the Connect REST API with the below config:
83+
84+
**URL**
85+
86+
- The URL of the API you want to call (ex, `https://slack.com/api/chat.postMessage`)
87+
- When using the REST API, this should be an URL-safe Base64 encoded string (ex, `aHR0cHM6Ly9zbGFjay5jb20vYXBpL2NoYXQucG9zdE1lc3NhZ2U`)
88+
89+
**HTTP method**
90+
91+
- Use the HTTP method required by the downstream API
92+
93+
**Body**
94+
95+
- Optionally include a body to send to the downstream API
96+
97+
**Headers**
98+
99+
- If using the REST API, include the `Authorization` header with your Pipedream OAuth access token (`Bearer {access_token}`)
100+
- Headers that contain the prefix `x-pd-proxy` will get forwarded to the downstream API
101+
102+
```bash
103+
# First, obtain an OAuth access token
104+
curl -X POST https://api.pipedream.com/v1/oauth/token \
105+
-H "Content-Type: application/json" \
106+
-d '{
107+
"grant_type": "client_credentials",
108+
"client_id": "{your_oauth_client_id}",
109+
"client_secret": "{your_oauth_client_secret}"
110+
}'
111+
112+
# The response will include an access_token. Use it in the Authorization header below.
113+
114+
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}" \
115+
-H "Authorization: Bearer {access_token}" \
116+
-H "x-pd-environment: {development | production}" \
117+
-d '{
118+
"text": "hello, world",
119+
"channel": "C03NA8B4VA9"
120+
}'
121+
122+
# Parse and return the data you need
123+
```

‎docs-v2/pages/connect/api.mdx

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ You'll primarily use the browser SDK to let your users securely connect apps fro
7070
1. [Create a short-lived token on your server](#create-a-new-token)
7171
2. Initiate auth with that token to securely connect an account for a specific user
7272

73-
Here's a Next.js example [from our quickstart](/connect/quickstart):
73+
Here's a Next.js example [from our quickstart](/connect/managed-auth/quickstart):
7474

7575
```typescript
7676
import { createFrontendClient } from "@pipedream/sdk/browser"
@@ -408,7 +408,7 @@ You can find the app's ID in the response from the [List apps](/rest-api#list-ap
408408

409409
`oauth_app_id` **string** (_optional_)
410410

411-
The ID of the [OAuth app](/connect/quickstart#create-a-pipedream-oauth-client) you'd like to retrieve accounts for.
411+
The ID of the [OAuth app](/connect/managed-auth/quickstart#create-a-pipedream-oauth-client) you'd like to retrieve accounts for.
412412

413413
---
414414

@@ -427,7 +427,7 @@ Never return user credentials to the client
427427
</Callout>
428428

429429
<Callout type="info">
430-
To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/oauth-clients#using-pipedream-oauth).
430+
To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/managed-auth/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/managed-auth/oauth-clients#using-pipedream-oauth).
431431
</Callout>
432432

433433
##### Examples
@@ -680,7 +680,7 @@ Never return user credentials to the client
680680
</Callout>
681681

682682
<Callout type="info">
683-
To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/oauth-clients#using-pipedream-oauth).
683+
To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/managed-auth/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/managed-auth/oauth-clients#using-pipedream-oauth).
684684
</Callout>
685685

686686
##### Examples
@@ -927,7 +927,7 @@ DELETE /{project_id}/apps/{app_id}/accounts
927927

928928
`app_id` **string**
929929

930-
The app ID for which you want to delete all connected accounts. `app_id` can be `oauth_app_id` for [OAuth apps](/connect/quickstart#create-a-pipedream-oauth-client) or name slug for key-based apps, which you can find under the **Authentication** section of any [app page](https://pipedream.com/apps)
930+
The app ID for which you want to delete all connected accounts. `app_id` can be `oauth_app_id` for [OAuth apps](/connect/managed-auth/quickstart#create-a-pipedream-oauth-client) or name slug for key-based apps, which you can find under the **Authentication** section of any [app page](https://pipedream.com/apps)
931931

932932
##### Examples
933933

‎docs-v2/pages/connect/components.mdx

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,33 @@
11
import { Steps, Tabs } from 'nextra/components'
22
import Callout from '@/components/Callout'
33

4-
# Embedding components in your application
4+
# Pre-built tools for your app or agent
55

6-
Pipedream Connect provides APIs to embed [pre-built components](/components) directly in your application
7-
or AI agent, unlocking access to {process.env.REGISTRY_COMPONENTS}+ pre-built API operations. Enable [your end users](/connect/api#external-users) to
6+
Pipedream Connect provides APIs to embed pre-built tools ([triggers and actions](/components)) directly in your application
7+
or AI agent, enabling access to 10,000+ built-in API operations. Enable [your end users](/connect/api#external-users) to
88
configure, deploy, and invoke Pipedream triggers and actions for more than {process.env.PUBLIC_APPS} APIs.
99

10-
## What are components?
10+
## What are triggers and actions?
1111

12-
In Pipedream, [components](/components) are self-contained executable units of code. Your end users configure the inputs and the components produce a
12+
In Pipedream, we call triggers and actions [components](/components), which are self-contained executable units of code. Your end users configure the inputs and these components produce a
1313
result that's exported as output. These components are developed and maintained by Pipedream
1414
and our community and their source code is available in our [public Github repo](https://github.com/PipedreamHQ/pipedream/tree/master/components).
1515

16+
## Implementation
17+
18+
### Use Pipedream's frontend SDK
19+
- Pipedream provides a frontend React SDK to enable your users to configure and run triggers and actions in your app's UI
20+
- Style the UI components however you want to match the design of your app, and you can also fork the SDK
21+
- Refer to the [SDK](https://github.com/PipedreamHQ/pipedream/blob/master/packages/connect-react/README.md) to get started
22+
1623
<Callout type="info">
17-
Running components for your end users via Pipedream Connect is in **beta**, and we're looking for feedback. Please [let us know](https://pipedream.com/support) how you're using it, what's not working, and what else you'd like to see.
24+
Check out the [public demo app](https://pdrm.co/connect) to see the API and SDK in action. You can also [run it locally and explore the code](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/connect-react-demo).
1825
</Callout>
1926

27+
### Use your own frontend
28+
- See below to get started with the REST API
29+
- Refer to the [full API reference](/connect/api#components) for supported SDK methods as well
30+
2031
## Getting started
2132

2233
<Callout type="info">

‎docs-v2/pages/connect/environments.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import Image from 'next/image'
66
Pipedream Connect projects support two environments: `development` and `production`. Connected accounts and credentials stored in `development` remain separate from `production`.
77

88
<Callout type="info">
9-
Pipedream customers on any plan can use all of the Connect features in `development` mode. To use Connect in `production`, click **Contact Sales** [here](https://pipedream.com/pricing?plan=Enterprise) to get in touch with our team.
9+
You can use all of the Connect features in `development` mode **on any plan**. **[Get in touch with our Sales team](https://pipedream.com/pricing?plan=Enterprise)** when you're ready to ship to production.
1010
</Callout>
1111

1212

‎docs-v2/pages/connect/index.mdx

Lines changed: 17 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -5,28 +5,33 @@ import VideoPlayer from "@/components/VideoPlayer";
55

66
# Pipedream Connect
77

8-
Pipedream Connect is the easiest way for your users to connect to [over {process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps), **right in your product**. You can build in-app messaging, CRM syncs, AI agents, [and much more](/connect/use-cases), all in a few minutes. Visit [the quickstart](/connect/quickstart) to build your first integration.
8+
**Connect provides a developer toolkit that lets you add {process.env.PUBLIC_APPS}+ integrations to your app or AI agent.** You can build AI agents, in-app messaging, CRM syncs, [and much more](/connect/use-cases), all in a few minutes. You have full, code-level control over how these integrations work in your app. You handle your product, Pipedream simplifies the integration.
99

10-
You have full, code-level control over how these integrations work in your app. You handle your product, Pipedream simplifies the integration.
10+
![Connect visualization](https://res.cloudinary.com/pipedreamin/image/upload/v1738731467/pd-connect-viz_cep0uq.png)
1111

12-
Connect lets you:
12+
## Use managed auth
1313

14-
1. Handle authorization or accept API keys on behalf of your users, for any of Pipedream's [{process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps). Use the [Client SDK](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk) or [Connect Link](/connect/quickstart#or-use-connect-link) to accept auth in minutes.
15-
2. Securely retrieve OAuth access tokens, API keys, and other credentials for your end users with Pipedream's [REST API](/connect/api).
16-
3. [Embed any Pipedream action or trigger](/connect/components) to run on behalf of your users, directly from within your application.
17-
4. [Run workflows](/connect/workflows) for your end users with Pipedream's [workflow builder](/workflows), [serverless runtime](/), and thousands of no-code [triggers](/workflows/triggers) and [actions](/workflows/actions). Build complex integrations in minutes, writing code when you need it and using no-code components when you don't. Pipedream workflows are easy to modify, debug, and scale.
14+
- Handle authorization or accept API keys on behalf of your users, for any of Pipedream's [{process.env.PUBLIC_APPS}+ APIs](https://pipedream.com/apps)
15+
- Use the [Client SDK](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk) or [Connect Link](/connect/managed-auth/quickstart#or-use-connect-link) to accept auth in minutes
16+
- Ship new integrations quickly with Pipedream's approved OAuth clients, or use your own
1817

19-
<br />
2018

21-
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1724194758/Screenshot_2024-08-20_at_3.59.05_PM_rfylfq.png" alt="Pipedream Connect overview" width={800} height={529} />
19+
## Act on behalf of your users
20+
21+
- Retrieve OAuth access tokens and API keys for your end users with Pipedream's [REST API](/connect/api)
22+
- Add 10,000+ pre-built tools and triggers from {process.env.PUBLIC_APPS}+ APIs to your AI agent or embed them directly in your SaaS app
23+
- Develop and deploy complex multi-step [workflows](/connect/workflows) in our [visual workflow builder](/workflows)
24+
- Use the Connect proxy to make custom API requests
25+
26+
{/* <Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1724194758/Screenshot_2024-08-20_at_3.59.05_PM_rfylfq.png" alt="Pipedream Connect overview" width={800} height={529} /> */}
2227

2328
## Use cases
2429

2530
Pipedream Connect lets you build any API integration into your product in minutes. Our customers build:
2631

32+
- **AI products**: Talk to any AI API or LLM, interacting with your users or running AI-driven asynchronous tasks
2733
- **In-app messaging**: Send messages to Slack, Discord, Microsoft Teams, or any app directly from your product.
2834
- **CRM syncs**: Sync data between your app and Salesforce, HubSpot, or any CRM
29-
- **AI products**: Talk to any AI API or LLM, interacting with your users or running AI-driven asynchronous tasks
3035
- **Spreadsheet integrations**: Sync data between your app and Google Sheets, Airtable, or any spreadsheet
3136

3237
[and much more](/connect/use-cases).
@@ -35,33 +40,9 @@ Pipedream Connect lets you build any API integration into your product in minute
3540

3641
Visit [the managed auth quickstart](/connect/quickstart) to build your first integration.
3742

38-
## App configuration for OAuth apps
39-
40-
Pipedream has more than {process.env.PUBLIC_APPS} apps available for you to integrate via Connect. Getting started is easy — just follow the [quickstart](/connect/quickstart) to get up and running.
41-
42-
By default, apps that use OAuth to authenticate will use Pipedream's OAuth client. Depending on your use case, you may need to configure your own OAuth client. Read more about OAuth clients in Pipedream [here](/connected-accounts/oauth-clients).
43-
44-
[Let us know](https://pipedream.com/support) if the app you're looking for isn't listed [here](https://pipedream.com/apps).
45-
46-
## Users
47-
48-
To view or delete your users' connected accounts:
49-
50-
1. Open your project in Pipedream
51-
2. Click the **Connect** tab on the left
52-
3. Click the **Users** tab at the top
53-
54-
You'll see a list of all users, their connected accounts, and the option to delete any accounts from the UI. You can also retrieve and delete all your users via the API ([see the docs for reference](/connect/api)).
55-
56-
<Callout type="warning">
57-
Connect currently supports one connected account per user, app, environment combination.
58-
59-
So if user `abc-123` in your application connects their Slack account in `production`, then that same user connects a different Slack workspace (also in `production`), the first connected account will get overwritten in Pipedream and replaced by the second.
60-
</Callout>
61-
6243
## Plans and pricing
6344

64-
**Managed authentication with Connect is free to use for up to 1,000 connected accounts for any workspace**. Check out our [pricing page](https://pipedream.com/pricing?plan=Enterprise) for details on running workflows and embedding components in your app.
45+
**Managed authentication with Connect is free to use for up to 1,000 connected accounts for any workspace**. Check out our [pricing page](https://pipedream.com/pricing?plan=Enterprise) to get in touch with our Sales team for details on using Connect in production.
6546

6647
## Security
6748

@@ -84,4 +65,4 @@ All credentials and tokens are sent to Pipedream securely over HTTPS, and encryp
8465
- **Developer**: This is probably you, the Pipedream customer who's developing an app and wants to use Connect to make API requests on behalf of your end users.
8566
- **End User**: Your customer or user, whose data you want to access on their behalf. End users are identifed via the `external_user_id` param in the Connect SDK and API.
8667
- **Connected Account**: The account your end user connects. [Read more about connected accounts](/connected-accounts).
87-
- **OAuth Client**: Custom OAuth clients you create in Pipedream. [Read more about OAuth clients](/connected-accounts/oauth-clients).
68+
- **OAuth Client**: This is admittedly a bit of an overloaded term and refers both to [custom OAuth clients](/connect/managed-auth/oauth-clients) you create in Pipedream to use when your end users authorize access to their account, as well as [OAuth clients to authenticate to Pipedream's API](/rest-api/auth#oauth).

0 commit comments

Comments
 (0)