Managed Auth Quickstart

Configure your environment

You’ll need to do two things to add Pipedream Connect to your app:

1. Connect to the Pipedream API from your server. 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 or redirect your users to a Pipedream-hosted URL to start the account connection flow.

We’ll walk through these steps below with an interactive demo that lets you see an execute the code directly in the docs.

If you’re building your own app, you’ll need to provide these credentials to the environment, or retrieve them from your secrets store:

# Used to authorize requests to the Pipedream API
PIPEDREAM_CLIENT_ID=your_client_id
PIPEDREAM_CLIENT_SECRET=your_client_secret
PIPEDREAM_PROJECT_ENVIRONMENT=development
PIPEDREAM_PROJECT_ID=your_project_id

Create a project in Pipedream

1. Open an existing Pipedream project or create a new one at pipedream.com/projects.
2. Click the Settings tab, then copy your Project ID.

Create a Pipedream OAuth client

Pipedream uses OAuth to authorize requests to the REST API. To create an OAuth client:

1. Visit the API settings for your workspace.
2. Click the New OAuth Client button.
3. Name your client and click Create.
4. Copy the client secret. It will not be accessible again. Click Close.
5. Copy the client ID from the list.

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 to generate a short-lived token for your users and use that in the account connection flow. See the docs on Connect tokens for a general overview of why we need to create tokens and scope them to end users.

In the code below you can see how we generate a Connect token for an example user, and even try it yourself:

import { createBackendClient } from "@pipedream/sdk/server";
 
// This code runs on your server
const pd = createBackendClient({
  environment: "development", 
  credentials: {
    clientId: process.env.PIPEDREAM_CLIENT_ID,
    clientSecret: process.env.PIPEDREAM_CLIENT_SECRET,
  },
  projectId: process.env.PIPEDREAM_PROJECT_ID
});
 
// Create a token for a specific user
const { token, expires_at, connect_link_url } = await pd.createConnectToken({
  external_user_id: "YOUR_USER_ID", 
});

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.

Connect your user’s account

To connect a third-party account for a user, you have two options:

1. Use the Pipedream SDK in your frontend
2. Use Connect Link to deliver a hosted URL to your user

Use the Pipedream SDK in your frontend

Use this method when you want to handle the account connection flow yourself, in your app. For example, you might want to show a Connect Slack button in your app that triggers the account connection flow.

First, install the Pipedream SDK in your frontend:

npm i --save @pipedream/sdk

When the user connects an account in your product, pass the token from your backend and call connectAccount. This opens a Pipedream iFrame that guides the user through the account connection.

Try the interactive demo below to connect an account after generating a token in the previous step:

import { createFrontendClient } from "@pipedream/sdk/browser"
 
// This code runs in the frontend using the token from your server
export default function Home() {
  function connectAccount() {
  const pd = createFrontendClient()
    pd.connectAccount({
      app: "google_sheets", 
      token: "{connect_token}", 
      onSuccess: (account) => {
        // Handle successful connection
        console.log(`Account successfully connected: ${account.id}`)
      },
      onError: (err) => {
        // Handle connection error
        console.error(`Connection error: ${err.message}`)
      }
    })
  }

  return (
    <main>
      <button onClick={connectAccount}>Connect Account</button>
    </main>
  )
}

Or use Connect Link

Use this option when you can’t execute JavaScript or open an iFrame in your environment (e.g. mobile apps) and instead want to share a URL with your end users.

The Connect Link URL opens a Pipedream-hosted page, guiding users through the account connection process. The URL is specific to the user and expires after 4 hours.

After generating a token in the step above, you can use the resulting Connect Link URL. Try it below:

Make authenticated requests

Now that your users have connected an account, you can use their auth in one of a few ways:

1. Retrieve their credentials from the REST API to use in your backend application
2. Use Pipedream’s visual workflow builder to define complex logic to run on behalf of your users
3. Embed Pipedream components directly in your app to run actions and triggers on their behalf

Deploy your app to production

• Test end to end in development
• Ship to production!