Skip to content

Updating quickstart in docs based on apps UI #13987

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 20, 2024
Merged

Updating quickstart in docs based on apps UI #13987

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
10ef6b9
Updating based on apps UI
dannyroosevelt Sep 18, 2024
2fdc30e
Merge branch 'master' into danny/connect-apps-linking-docs
dannyroosevelt Sep 19, 2024
a2ee3ab
review feedback
dannyroosevelt Sep 19, 2024
a9e1a5d
Merge branch 'master' into danny/connect-apps-linking-docs
dannyroosevelt Sep 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs-v2/pages/connect/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,19 +73,19 @@ 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we keep this and just put it down bottom? I believe we still link to this section elsewhere


- **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
- Simplify the developer experience and SDK integration
- 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!
- 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).
50 changes: 12 additions & 38 deletions docs-v2/pages/connect/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,47 +28,24 @@ And here's the technical flow between your frontend, backend, and Pipedream's AP

<Steps>

### 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**.

<br />
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1723760323/google-sheets-name-slug_gwa4rb.png" alt="Google Sheets name slug" width={550} height={300} />

#### 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.

<Callout type="warning">
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.

<br />
<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1723760958/enable-oauth-client-for-pd-connect_ipkzmo.png" alt="Enable OAuth client for Pipedream Connect" width={450} height={300} />
</Callout>

Once that's done, copy the **OAuth App ID** from the app configuration.

<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1723761240/copy-oauth-app-id_on6d8p.png" alt="Copy your OAuth app ID" width={550} height={300} />
**OAuth apps require you [create your own OAuth client](#creating-a-custom-oauth-client):**
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

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.
Expand All @@ -77,7 +54,7 @@ You'll need these when configuring the SDK and making API requests.

<Image src="https://res.cloudinary.com/pipedreamin/image/upload/v1724773559/connect-keys_cb4ujt.png" alt="Project keys in the Connect tab" width={650} height={300} />

### 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:

Expand All @@ -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
Expand All @@ -113,7 +86,8 @@ If you're building your own app, you'll need to provide these values to the envi

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.

</Callout>
Expand Down
Loading