diff --git a/docs-v2/pages/connect/_meta.tsx b/docs-v2/pages/connect/_meta.tsx index 41958fea4e0ed..8092943c9234b 100644 --- a/docs-v2/pages/connect/_meta.tsx +++ b/docs-v2/pages/connect/_meta.tsx @@ -6,7 +6,7 @@ export default { "title": "Use cases", }, "quickstart": { - "title": "Quickstart", + "title": "Managed auth", }, "workflows": { "title": "Running workflows", @@ -32,12 +32,12 @@ export default { "connect-link": { "title": "Connect Link", }, - "troubleshooting": { - "title": "Troubleshooting", - }, "customize-your-app": { "title": "Customize your app", }, + "troubleshooting": { + "title": "Troubleshooting", + }, "migrating-from-project-keys-to-oauth": { "display": "hidden", }, diff --git a/docs-v2/pages/connect/components.mdx b/docs-v2/pages/connect/components.mdx index efe46f3c1b243..b65328b1defde 100644 --- a/docs-v2/pages/connect/components.mdx +++ b/docs-v2/pages/connect/components.mdx @@ -1,44 +1,35 @@ import { Steps, Tabs } from 'nextra/components' -import ArcadeEmbed from '@/components/ArcadeEmbed' import Callout from '@/components/Callout' -import Image from 'next/image' # Running components for your end users -Pipedream Connect provides you with the ability to pre-configure, deploy and -invoke [components](/components) **on behalf of [your end -users](/connect/api#external-users)**. +Pipedream Connect provides APIs to embed [pre-built components](/components) directly in your application +or AI agent, unlocking access to thousands of pre-built API operations. Enable [your end users](/connect/api#external-users) to +configure, deploy, and invoke Pipedream triggers and actions for more than {process.env.PUBLIC_APPS} APIs. ## What are components? -In the context of Pipedream Connect, components are self-contained executable -units of code. They are usually provided with some arbitrary input and produce a -result that's exported as output. These components are developed by the -Pipedream community and their source code is available in our [public Github -repository](https://github.com/PipedreamHQ/pipedream/tree/master/components). - -To learn more about components in detail, please visit our [Components -guide](/components). +In Pipedream, [components](/components) are self-contained executable units of code. Your end users configure the inputs and the components produce a +result that's exported as output. These components are developed and maintained by Pipedream +and our community and their source code is available in our [public Github repo](https://github.com/PipedreamHQ/pipedream/tree/master/components). 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. -## How to run components for your end users +## Getting stated Refer to the [Connect API docs](/connect/api) for the full API reference. Below is a quickstart with a few specific examples. + +You can skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components). ### Find the app you want to use - -You can also skip steps 1 and 2 if you already know the component you want to use or if you'd prefer to [pass a natural language prompt to Pipedream's component search API](/rest-api#search-for-registry-components). - - -In order to find the right trigger or action to configure and run, you first need to find the app. For this example, we'll search for `gitlab`. +In order to find the right trigger or action to configure and run, you first need to find the app. In this example, we'll search for `gitlab`. ```text GET /v1/connect/apps?q=gitlab @@ -145,7 +136,7 @@ Here's the response: ``` ### Retrieve the component's definition -In order to run a component for your end users, you need to understand +To configure and run a component for your end users, you need to understand the component's definition. Now that you have the component's key from the previous step, you can retrieve its structure from the Pipedream API. See the [component structure](/components/api#component-structure) section in our docs for more @@ -158,11 +149,10 @@ Commits** action for Gitlab: GET /v1/connect/components/gitlab-list-commits ``` -The response will contain the component's structure, including its -(human-understandable) name, version, and most importantly, the configuration -options that the component accepts (also known as [props](/components/api#props) -or "properties"). Here's an example of the response for the component in the -example above: +The response will contain the component's structure, including its user-friendly name, +version, and most importantly, the configuration options the component accepts +(also known as [props](/components/api#props) or "properties"). +Here's an example of the response for the component in the example above: ```json { @@ -213,9 +203,8 @@ Component execution on behalf of your end users requires a few preliminary steps, focused on getting the right input parameters (aka [props](/workflows/using-props)) to the component. -Configuring each prop for a component usually involves an API call to our -backend to retrieve the possible values, unless the values that a prop can take -are static/free-form. The endpoint is accessible at: +Configuring each prop for a component often involves an API call to retrieve the possible values, +unless the values that a prop can take are static or free-form. The endpoint is accessible at: ```text POST /v1/connect/components/configure @@ -224,7 +213,7 @@ POST /v1/connect/components/configure Typically, the options for a prop are linked to a specific user's account. Each of these props implements an `options` method that retrieves the necessary options from the third-party API, formats them, and sends them back in the -response for the end user to select. +response for the end user to select. Examples are listing Slack channels, Google Sheets, etc. The payload for the configuration API call must contain the following fields: @@ -235,7 +224,7 @@ The payload for the configuration API call must contain the following fields: configured. The initial configuration call must contain the ID of the account (aka `authProvisionId`) that your user has connected to the target app (see [this section](workflows#configure-accounts-to-use-your-end-users-auth) for - more details on how to create these accounts) + more details on how to create these accounts). We'll use the [**List Commits** component for Gitlab](https://github.com/PipedreamHQ/pipedream/blob/master/components/gitlab/actions/list-commits/list-commits.mjs#L4) @@ -344,7 +333,7 @@ For example, to retrieve the configuration options for the `refName` prop: ### Configure dynamic props (optional) -The set of props that a component can accept might not be static, and can change +The set of props that a component can accept might not be static, and may change depending on the values of prior props. Props that behave this way are called [dynamic props](/components/api#dynamic-props), and they need to be configured in a different way. Props that are dynamic will have a `reloadProps` attribute @@ -361,7 +350,7 @@ The payload is similar to the one used for the configuration API, but it excludes the `prop_name` field since the goal of this call is to reload and retrieve the new set of props, not to configure a specific one. -Using the **Add Single Row** component for Google Sheets as an example, the +Using the [Add Single Row action for Google Sheets](https://pipedream.com/apps/google-sheets/actions/add-single-row) as an example, the request payload would look like this: ```json @@ -455,7 +444,8 @@ Actions are components that perform a task by taking an input either during produce a result. Sources are very similar, but the difference is that they are not invoked directly by Pipedream users, but rather by events that happen on a third-party service. For example, the "New File" source for Google Drive will be -triggered every time a new file is created in a specific folder in Google Drive. +triggered every time a new file is created in a specific folder in Google Drive, +then will emit an event for you to consume. All this means is that actions can be invoked manually on demand, while sources are instead deployed and run automatically when the event they are listening for @@ -545,7 +535,7 @@ look something like this: ```json { - "external_user_id": "jverce", + "external_user_id": "demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9", "id": "gitlab-new-issue", "prop_name": "http", "configured_props": { @@ -608,7 +598,7 @@ this: "type": "$.service.db" }, "http": { - "endpoint_url": "https://39643dc2c8ff98a019f3fdc9078d6db9.m.pipedream.net" + "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net" }, "projectId": 45672541 }, @@ -625,7 +615,7 @@ In the example above, the source ID is `dc_dAuGmW7`, which can be used to delete the source in the future: ```text -DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=jverce +DELETE /v1/connect/deployed-triggers/dc_dAuGmW7?external_user_id=demo-20a1b80e-23a5-4d4d-a8ef-c91cdbd0dad9 ``` diff --git a/docs-v2/pages/connect/environments.mdx b/docs-v2/pages/connect/environments.mdx index 5a8b78214b4b8..8be50f4040661 100644 --- a/docs-v2/pages/connect/environments.mdx +++ b/docs-v2/pages/connect/environments.mdx @@ -10,7 +10,7 @@ Pipedream customers on any plan can use all of the Connect features in `developm -## How to specify environment +## How to specify the environment You specify the environment when [creating a new Connect token](/connect/api/#create-a-new-token) with the Pipedream SDK or API. When users succesfully connect their account, Pipedream saves the account credentials (API key, access token, etc) for that `external_user_id` in the specified environment. @@ -41,7 +41,7 @@ curl -X POST https://api.pipedream.com/v1/connect/{project_id}/tokens \ ``` -When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use the `development` environment with your own accounts when testing and developing, and not with your end users.** +When connecting an account in `development`, make sure you're signed in to pipedream.com in the same browser where you're connecting your account. This is only a requirement for the `development` environment. **You should only use `development` with your own accounts when testing and developing, and not with your end users.**
diff --git a/docs-v2/pages/connect/index.mdx b/docs-v2/pages/connect/index.mdx index 1090173fb36ee..09cb3c5675242 100644 --- a/docs-v2/pages/connect/index.mdx +++ b/docs-v2/pages/connect/index.mdx @@ -11,10 +11,10 @@ You have full, code-level control over how these integrations work in your app. Connect lets you: -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#use-connect-link) to accept auth in minutes. +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. 2. Securely retrieve OAuth access tokens, API keys, and other credentials for your end users with Pipedream's [REST API](/connect/api) -3. Run 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. -4. Run [any Pipedream action](https://pipedream.com/explore) or [deploy any Pipedream trigger](https://pipedream.com/explore) on behalf of your users, directly from within your application. +3. [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. +4. [Embed any Pipedream action or trigger](/connect/components) to run on behalf of your users, directly from within your application.
@@ -61,7 +61,7 @@ So if user `abc-123` in your application connects their Slack account in `produc ## Plans and pricing -**Connect is free to use for up to 1,000 connected accounts for any workspace**. +**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. ## Security diff --git a/docs-v2/pages/connect/oauth-clients.mdx b/docs-v2/pages/connect/oauth-clients.mdx index 8bcc2db82abfa..68e46140b7e23 100644 --- a/docs-v2/pages/connect/oauth-clients.mdx +++ b/docs-v2/pages/connect/oauth-clients.mdx @@ -30,7 +30,7 @@ For any OAuth app that supports it, **you can always use your own client.** Your 1. Follow the steps [here](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) to create an OAuth client in Pipedream. 2. When connecting an account either via the [frontend SDK](/connect/quickstart#use-the-pipedream-sdk-in-your-frontend), make sure to include the `oauthAppId` in `pd.connectAccount()`. -3. If using [Connect Link](/connect/quickstart#use-connect-link), make sure to include the `oauthAppId` in the URL. +3. If using [Connect Link](/connect/quickstart#or-use-connect-link), make sure to include the `oauthAppId` in the URL. ### Finding your OAuth app ID diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx index 2ffc772aff6bb..10ada37868013 100644 --- a/docs-v2/pages/connect/quickstart.mdx +++ b/docs-v2/pages/connect/quickstart.mdx @@ -3,7 +3,7 @@ import { Steps, Tabs } from 'nextra/components' import Image from 'next/image' import VideoPlayer from "@/components/VideoPlayer"; -# Quickstart +# Managed Auth Quickstart 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. @@ -29,7 +29,7 @@ Here's how Connect sits in your frontend and backend, and communicates with Pipe You'll need to do two things to add Pipedream Connect to your app: 1. [Connect to the Pipedream API from your server](#generate-a-short-lived-token). This lets you make secure calls to the Pipedream API to initiate the account connection flow and retrieve account credentials. If you're running a JavaScript framework like Node.js on your server, you can use the Pipedream SDK. -2. [Add the Pipedream SDK to your frontend](#connect-a-users-account) or redirect your users to [a Pipedream-hosted URL](/connect/connect-link) to start the account connection flow. +2. [Add the Pipedream SDK to your frontend](#connect-your-users-account) or redirect your users to [a Pipedream-hosted URL](/connect/connect-link) to start the account connection flow. We'll walk through these steps below, using [an example Next.js app](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/managed-auth-basic-next-app/). To follow along, clone [the repo](https://github.com/PipedreamHQ/pipedream-connect-examples/) and follow the instructions in [the app's `README`](https://github.com/PipedreamHQ/pipedream-connect-examples/tree/master/managed-auth-basic-next-app/). That will run the app on `localhost:3000`. @@ -74,7 +74,7 @@ You'll need these when configuring the SDK and making API requests. ### Generate a short-lived token -To securely initiate account connections for your users, you'll need generate a short-lived token for your users and use that in the [account connection flow](#connect-a-users-account). See [the docs on Connect tokens](/connect/tokens) for a general overview of why we need to create tokens and scope them to end users. +To securely initiate account connections for your users, you'll need generate a short-lived token for your users and use that in the [account connection flow](#connect-your-users-account). See [the docs on Connect tokens](/connect/tokens) for a general overview of why we need to create tokens and scope them to end users. In the Next.js example here, we're running [Next server components](https://nextjs.org/docs/app/building-your-application/rendering/server-components) in `app/server.ts`. We call the `serverConnectTokenCreate` method from the frontend to retrieve a token **for a specific user**. @@ -88,18 +88,18 @@ const { token, expires_at } = await serverConnectTokenCreate({ If you're using a different server / API framework, you'll need to make secure calls to that API to create a new token for your users. -Once you have a token, return it to your frontend to start the account connection flow for the user, or redirect them to a Pipedream-hosted URL with [Connect Link](#use-connect-link). +Once you have a token, return it to your frontend to start the account connection flow for the user, or redirect them to a Pipedream-hosted URL with [Connect Link](#or-use-connect-link). Refer to the API docs for [full set of parameters you can pass](/connect/api#create-a-new-token) in the `ConnectTokenCreate` call. -### Connect a user's account +### Connect your user's account To connect a third-party account for a user, you have two options: 1. [Use the Pipedream SDK](#use-the-pipedream-sdk-in-your-frontend) in your frontend -2. [Use Connect Link](#use-connect-link) to deliver a hosted URL to your user +2. [Use Connect Link](#or-use-connect-link) to deliver a hosted URL to your user #### Use the Pipedream SDK in your frontend @@ -144,7 +144,7 @@ export default function Home() { Press that button to connect an account for the app you configured. -#### Use Connect Link +#### Or use Connect Link Use this option when you can't execute JavaScript or open an iFrame in your environment (e.g. mobile apps), or when you want to offload the account connection flow to Pipedream and avoid frontend work. You can also send these links via email or SMS. @@ -160,70 +160,17 @@ https://pipedream.com/_static/connect.html?token={token}&connectLink=true&app={a 4. Redirect your users to this URL, or send it to them via email, SMS, and more. -### Retrieve the credentials from the backend +### Make authenticated requests -Once your user connects an account, you can retrieve their credentials from your backend. +Now that your users have connected an account, you can use their auth in one of a few ways: -This example shows you how to fetch credentials by your end user's `external_user_id`. You can also fetch all connected accounts for a specific app, or a specific user — see the [Connect API reference](/connect/api). - - - -```typescript -import { - createBackendClient, -} from "@pipedream/sdk/server"; - -const pd = createBackendClient({ - environment: "development", // change to production if running for a test production account, or in production - credentials: { - clientId: "{oauth_client_id}", - clientSecret: "{oauth_client_secret}", - }, - projectId: "{your_project_id}" -}); - -async function getUserAccounts(external_user_id: string, include_credentials: boolean = false) { - await pd.getAccounts({ - external_user_id, - include_credentials, // set to true to include credentials - }) - - // Parse and return the data you need. These may contain credentials, - // which you should never return to the client -} -``` - - -```javascript -import { - createBackendClient, -} from "@pipedream/sdk/server"; - -const pd = createBackendClient({ - environment: "development", // change to production if running for a test production account, or in production - credentials: { - clientId: "{oauth_client_id}", - clientSecret: "{oauth_client_secret}", - }, - projectId: "{your_project_id}" -}); - -async function getUserAccounts(external_user_id, include_credentials = false) { - await pd.getAccounts({ - external_user_id, - include_credentials, // set to true to include credentials - }) - - // Parse and return the data you need. These may contain credentials, - // which you should never return to the client -} -``` - - +1. [Retrieve their credentials from the REST API](/connect/api#accounts) to use in your backend application +2. [Use Pipedream's visual workflow builder](/connect/workflows) to define complex logic to run on behalf of your users +3. [Embed Pipedream components directly in your app](/connect/components) to run actions and triggers on their behalf ### Deploy your app to production -- Now that you've successfully connected an account and retrieved the credentials, you're almost done! -- Learn about [development environments](/connect/environments) and [using OAuth clients](/connect/oauth-clients) to deploy your app to production. +- Test end to end in [development](/connect/environments) +- Ship to production! diff --git a/docs-v2/pages/connect/troubleshooting.mdx b/docs-v2/pages/connect/troubleshooting.mdx index 8a81d5195f990..a0d63c2dbbbcc 100644 --- a/docs-v2/pages/connect/troubleshooting.mdx +++ b/docs-v2/pages/connect/troubleshooting.mdx @@ -38,7 +38,7 @@ Connect tokens expire, and are only able to be used once. Try generating a new t _App not found. Please check your app id._ -Double-check the app slug you're passing [when connecting your user's account](/connect/quickstart#connect-a-users-account). +Double-check the app slug you're passing [when connecting your user's account](/connect/quickstart#connect-your-users-account). ### Connection failed. Please retry or contact support. diff --git a/docs-v2/pages/connect/workflows.mdx b/docs-v2/pages/connect/workflows.mdx index d3e42ffd72889..a6574b69bc22b 100644 --- a/docs-v2/pages/connect/workflows.mdx +++ b/docs-v2/pages/connect/workflows.mdx @@ -30,7 +30,7 @@ Workflows also have built-in: Read [the quickstart](/quickstart/) to learn more. -## How to run workflows for your end users +## Getting started diff --git a/docs-v2/pages/privacy-and-security/index.mdx b/docs-v2/pages/privacy-and-security/index.mdx index 9564dea0a0773..98f75653b2bfd 100644 --- a/docs-v2/pages/privacy-and-security/index.mdx +++ b/docs-v2/pages/privacy-and-security/index.mdx @@ -133,7 +133,7 @@ Tokens expire after 4 hours, at which point you must create a new token for that ### Connect Link -You can also use [Connect Link](/connect/quickstart#use-connect-link) to generate a URL that initiates the authorization flow for a specific user. This is useful when you want to initiate the auth flow from a client-side environment that can't run JavaScript, or include the link in an email, chat message, etc. +You can also use [Connect Link](/connect/connect-link) to generate a URL that initiates the authorization flow for a specific user. This is useful when you want to initiate the auth flow from a client-side environment that can't run JavaScript, or include the link in an email, chat message, etc. Like tokens, Connect Links are coupled to specific users, and expire after 4 hours. diff --git a/docs-v2/vercel.json b/docs-v2/vercel.json index 47a7da8e3ed6f..8a7d4e042f637 100644 --- a/docs-v2/vercel.json +++ b/docs-v2/vercel.json @@ -281,6 +281,14 @@ { "source": "/docs/connected-accounts/api", "destination": "/docs/connect/api#accounts" + }, + { + "source": "/docs/connect/quickstart#use-connect-link", + "destination": "/docs/connect/quickstart#or-use-connect-link" + }, + { + "source": "/docs/connect/quickstart#connect-a-users-account", + "destination": "/docs/connect/quickstart#connect-your-users-account" } ] }