From 10ef6b9000cb419ff58d71099afafe8aa9998f1d Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Tue, 17 Sep 2024 21:31:40 -0700 Subject: [PATCH 1/2] Updating based on apps UI --- docs-v2/pages/connect/index.mdx | 8 ----- docs-v2/pages/connect/quickstart.mdx | 51 +++++++--------------------- 2 files changed, 12 insertions(+), 47 deletions(-) diff --git a/docs-v2/pages/connect/index.mdx b/docs-v2/pages/connect/index.mdx index 5ecb1de2eca32..5fac4df4148f0 100644 --- a/docs-v2/pages/connect/index.mdx +++ b/docs-v2/pages/connect/index.mdx @@ -73,14 +73,6 @@ All credentials and tokens are sent to Pipedream securely over HTTPS, and encryp - **Use secure, session-based auth between your client and server** — authorize all requests from your client to your server using a secure, session-based auth mechanism. Use well-known identity providers with services like [Clerk](https://clerk.com/), [Firebase](https://firebase.google.com/), or [Auth0](https://auth0.com/) to securely generate and validate authentication tokens. The same follows for Pipedream workflows — if you trigger Pipedream workflows from your client or server, validate all requests in the workflow before executing workflow code. - **Secure your workflows** — See our [standard security practices](/privacy-and-security/best-practices) for recommendations on securing your Pipedream workflows. -## Glossary of terms - -- **App**: GitHub, Notion, Slack, Google Sheets, and more. The app is the API you want your users to connect to in your product. See the [full list here](https://pipedream.com/apps). -- **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. -- **End User**: Your customer or user, whose data you want to access on their behalf. End users are identifed via the `external_id` param in the Connect SDK and API. -- **Connected Account**: The account your end user connects. [Read more about connected accounts](/connected-accounts). -- **OAuth Client**: Custom OAuth clients you create in Pipedream. [Read more about OAuth clients](/connected-accounts/oauth-clients). - ## Product roadmap for Connect - Address bugs and feedback during the preview phase diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx index 6980782983d58..bb083dea6c159 100644 --- a/docs-v2/pages/connect/quickstart.mdx +++ b/docs-v2/pages/connect/quickstart.mdx @@ -28,47 +28,24 @@ And here's the technical flow between your frontend, backend, and Pipedream's AP -### Choose the apps you want to integrate +### Add the apps you want to integrate + +1. Open an existing Pipedream project or create a new one at [https://pipedream.com/projects](https://pipedream.com/projects). +2. Click the **Connect** tab, then select **Apps**. +3. From here, you can add any app to your project that you want to integrate with your application. There are two types of apps in Pipedream: 1. **Key-based**: These apps require static credentials, like API keys. Pipedream stores these credentials securely and exposes them via API. 2. **OAuth**: These apps require OAuth authorization. Pipedream manages the OAuth flow for these apps, ensuring you always have a fresh access token for requests. -Connecting Key-based apps with the Pipedream API requires only [the app's name slug](#find-your-apps-name-slug). OAuth apps require you to [create your own OAuth client](#creating-a-custom-oauth-client) and pass the OAuth app ID, as well. - -#### Find your app's name slug - -Typically, the name slug is the name of the app in lowercase, with spaces replaced by underscores. For example, the name slug for the GitHub app is `github`. The name slug for Google Sheets is `google_sheets`. - -To find the name slug for an app: - -1. Visit [https://pipedream.com/apps](https://pipedream.com/apps) -2. Search and select the app you want to integrate -3. In the **Authentication** section, copy the **Name slug**. - -
-Google Sheets name slug - -#### Creating a custom OAuth client - -First, [create an OAuth client](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) for the app you'd like to integrate. - - -Make sure to check the **Enable for Pipedream Connect** setting in the OAuth client configuration in Pipedream to allow your end users to connect their accounts. By default, OAuth clients are accessible only to members of your Pipedream workspace. Checking this box allows your end users to create accounts for this app, too. - -
-Enable OAuth client for Pipedream Connect - - -Once that's done, copy the **OAuth App ID** from the app configuration. - -Copy your OAuth app ID +**OAuth apps require you [create your own OAuth client](#creating-a-custom-oauth-client):** +- First, [create an OAuth client](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) for the app you'd like to integrate. +- Now when selecting an OAuth app in the **Apps** tab, you'll be prompted to select the OAuth client you've created. ### Get your project keys -1. Open an existing Pipedream project or create a new one at [https://pipedream.com/projects](https://pipedream.com/projects). -2. Visit the **Connect** tab, then select **Configuration**. +1. From within the the **Connect** tab in your project, select **Configuration**. 3. Find your project's **Public Key** and **Secret Key**. You'll need these when configuring the SDK and making API requests. @@ -77,7 +54,7 @@ You'll need these when configuring the SDK and making API requests. Project keys in the Connect tab -### Run the Pipedream demo app, or configure your own +### Run the Pipedream demo app or configure your own You'll need to do two things to integrate Pipedream Connect into your app: @@ -95,10 +72,6 @@ cp .env.example .env.local and fill the `.env.local` file with your project and app details: ```bash -# Specific to Next.js — see `app/page.tsx` for how these are used -NEXT_PUBLIC_PIPEDREAM_APP_SLUG=github -NEXT_PUBLIC_PIPEDREAM_APP_ID=oa_abc123 - # Used by `app/server.ts` to authorize requests to the Pipedream API — see below PIPEDREAM_PROJECT_PUBLIC_KEY=pub_abc123 PIPEDREAM_PROJECT_SECRET_KEY=sec_abc123 @@ -112,8 +85,8 @@ If you're building your own app, you'll need to provide these values to the envi **Why do I need to talk to the Pipedream API from my server?** You need to secure specific operations, for example: - -- You need to initiate the account connection flow for your end users. In Pipedream Connect, **you exchange your project keys for a short-lived token that allows a specific user to connect a specific app**, and return that token to your frontend. If you expose your Pipedream project keys directly to the frontend, anyone could initiate the account connection flow for any user, and you'd be charged for those accounts. +- You need to initiate the account connection flow for your end users. In Pipedream Connect, **you exchange your project keys for a short-lived token that allows a specific user to connect a specific app**, and return that token to your frontend. +- If you expose your Pipedream project keys directly to the frontend, anyone could initiate the account connection flow for any user, and you'd be charged for those accounts. - You need to retrieve account credentials for your end users. Again, this should happen securely on your server, not in the frontend, to protect your users' data. From a2ee3ab2b574f8ecf5347945858ce3e84cb3ff80 Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Wed, 18 Sep 2024 22:20:16 -0700 Subject: [PATCH 2/2] review feedback --- docs-v2/pages/connect/index.mdx | 10 +++++++++- docs-v2/pages/connect/quickstart.mdx | 5 +++-- 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/docs-v2/pages/connect/index.mdx b/docs-v2/pages/connect/index.mdx index 5fac4df4148f0..e738f3e4262ab 100644 --- a/docs-v2/pages/connect/index.mdx +++ b/docs-v2/pages/connect/index.mdx @@ -80,4 +80,12 @@ All credentials and tokens are sent to Pipedream securely over HTTPS, and encryp - Invoke Pipedream workflows on behalf of end users - Support hosted UIs for connecting accounts — native support for mobile environments that can't execute JavaScript or load iframes. - Improve error handling for Connect developers and end users -- And more! \ No newline at end of file +- And more! + +## Glossary of terms + +- **App**: GitHub, Notion, Slack, Google Sheets, and more. The app is the API you want your users to connect to in your product. See the [full list here](https://pipedream.com/apps). +- **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. +- **End User**: Your customer or user, whose data you want to access on their behalf. End users are identifed via the `external_id` param in the Connect SDK and API. +- **Connected Account**: The account your end user connects. [Read more about connected accounts](/connected-accounts). +- **OAuth Client**: Custom OAuth clients you create in Pipedream. [Read more about OAuth clients](/connected-accounts/oauth-clients). \ No newline at end of file diff --git a/docs-v2/pages/connect/quickstart.mdx b/docs-v2/pages/connect/quickstart.mdx index bb083dea6c159..85761d457f543 100644 --- a/docs-v2/pages/connect/quickstart.mdx +++ b/docs-v2/pages/connect/quickstart.mdx @@ -40,8 +40,8 @@ There are two types of apps in Pipedream: 2. **OAuth**: These apps require OAuth authorization. Pipedream manages the OAuth flow for these apps, ensuring you always have a fresh access token for requests. **OAuth apps require you [create your own OAuth client](#creating-a-custom-oauth-client):** -- First, [create an OAuth client](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) for the app you'd like to integrate. -- Now when selecting an OAuth app in the **Apps** tab, you'll be prompted to select the OAuth client you've created. +1. First, [create an OAuth client](/connected-accounts/oauth-clients#configuring-custom-oauth-clients) for the app you'd like to integrate. +2. Now when selecting an OAuth app in the **Apps** tab, you'll be prompted to select the OAuth client you've created. ### Get your project keys @@ -85,6 +85,7 @@ If you're building your own app, you'll need to provide these values to the envi **Why do I need to talk to the Pipedream API from my server?** You need to secure specific operations, for example: + - You need to initiate the account connection flow for your end users. In Pipedream Connect, **you exchange your project keys for a short-lived token that allows a specific user to connect a specific app**, and return that token to your frontend. - If you expose your Pipedream project keys directly to the frontend, anyone could initiate the account connection flow for any user, and you'd be charged for those accounts. - You need to retrieve account credentials for your end users. Again, this should happen securely on your server, not in the frontend, to protect your users' data.