Initial commit of workflow SDK / OAuth docs

components/air/air.app.mjs

@@ -8,4 +8,4 @@ export default {
       console.log(Object.keys(this.$auth));
     },
   },
-};
+};

components/imagior/imagior.app.mjs

@@ -8,4 +8,4 @@ export default {
       console.log(Object.keys(this.$auth));
     },
   },
-};
+};

components/nerv/nerv.app.mjs

@@ -8,4 +8,4 @@ export default {
       console.log(Object.keys(this.$auth));
     },
   },
-};
+};

components/runpod/runpod.app.mjs

@@ -8,4 +8,4 @@ export default {
       console.log(Object.keys(this.$auth));
     },
   },
-};
+};

components/teach_n_go/teach_n_go.app.mjs

@@ -8,4 +8,4 @@ export default {
       console.log(Object.keys(this.$auth));
     },
   },
-};
+};

docs-v2/pages/_meta.json

@@ -17,7 +17,7 @@
   "event-history": "Event History",
   "http": "HTTP",
   "environment-variables": "Environment Variables",
-  "rest-api": "API Reference",
+  "rest-api": "REST API",
   "cli": "CLI",
   "destinations": "Destinations",
   "user-settings": "User and Billing Settings",

docs-v2/pages/connect/api.mdx

@@ -43,6 +43,10 @@ or a specific version:
 
 ## Authentication
 
+### OAuth
+
+TO DO
+
 ### TypeScript SDK (Server)
 
 Most of your interactions with the Connect API will happen on the server, to protect API requests and user credentials. You'll use the SDK in [your frontend](#typescript-sdk-browser) to let users connect accounts. Once connected, you'll use the SDK on the server to retrieve credentials, invoke workflows on their behalf, and more.
@@ -100,21 +104,6 @@ export default function Home() {
 }
 ```
 
-### REST API
-
-You authenticate to the Connect API using **Basic Auth**. Send your project public key as the username and the project secret key as the password. When you make API requests, pass an
-`Authorization` header of the following format:
-
-```shell
-Authorization: Basic base_64(public_key:secret_key)
-```
-
-Clients like `cURL` will often make this easy. For example, here's how you list all accounts on a project:
-
-```shell
-curl 'https://api.pipedream.com/v1/connect/accounts' -u public_key:secret_key
-```
-
 ## External users
 
 When you use the Connect API, you'll pass an `external_id` parameter when initiating account connections and retrieving credentials. This is your user's ID, in your system — whatever you use to uniquely identify them. 
@@ -134,6 +123,32 @@ If you need higher rate limits, please [reach out](https://pipedream.com/support
 
 ## API Reference
 
+### Invoke workflows
+
+You can use the SDK to invoke workflows on behalf of your users. Here's an example of invoking a workflow with the SDK:
+
+```typescript
+import { createClient } from "@pipedream/sdk";
+
+const pd = createClient({
+  oauthClientId: "your-oauth-client-id",
+  oauthClientSecret: "your-oauth-client-secret",
+});
+
+const response = await pd.invokeWorkflow(
+  "https://your-workflow-url.m.pipedream.net",
+  {
+    body: {
+      foo: 123,
+      bar: "abc",
+    },
+    // pass any other fetch options here
+  },
+);
+```
+
+`invokeWorkflow` uses Node's `fetch` API, so you can pass any standard options in that object.
+
 ### Tokens
 
 Your app will initiate the account connection flow for your end users in your frontend. But you can't expose your project keys in the client, since they'd be accessible to anyone. Instead, on your server, **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.
@@ -576,11 +591,7 @@ response = client.connect_token_create(connect_token_opts[:external_id])
 
 #### List all accounts
 
-List all connected accounts for all end users within your project
-
-<Callout type="warning">
-This endpoint is not currently paginated, so we'll attempt to return all connected accounts for all users within your project. We intend to add pagination soon.
-</Callout>
+List all connected accounts for all end users within a project.
 
 ```
 GET /accounts/

docs-v2/pages/connect/index.mdx

@@ -55,7 +55,9 @@ Please let us know if you have any feedback on the value of Connect and how you'
 
 ## Security
 
-Pipedream takes the security of our products seriously. Please [review our security docs](/privacy-and-security) and send us any questions or [suspected vulnerabilities](/privacy-and-security#reporting-a-vulnerability). You can also get a copy of our [SOC 2 Type 2 report](/privacy-and-security#soc-2), [sign HIPAA BAAs](/privacy-and-security#hipaa), and get information on other practices and controls.
+Pipedream takes the security of our products seriously. See details on the security of the Connect product [here](/privacy-and-security#pipedream-connect).
+
+Please also [review our general security docs](/privacy-and-security) and send us any questions or [suspected vulnerabilities](/privacy-and-security#reporting-a-vulnerability). You can also get a copy of our [SOC 2 Type 2 report](/privacy-and-security#soc-2), [sign HIPAA BAAs](/privacy-and-security#hipaa), and get information on other practices and controls.
 
 ### Storing user credentials, token refresh
 

docs-v2/pages/connected-accounts/index.mdx

@@ -237,7 +237,11 @@ If you use a secrets store like [Pipedream Connect](/connect) or [HashiCorp Vaul
 
 ## Connecting to apps with IP restrictions
 
-If you're connecting to an app that enforces IP restrictions, you may need to whitelist Pipedream's IP addresses:
+<Callout type="info">
+These IP addresses are tied to **app connections only**, not workflows or other Pipedream services. To whitelist requests from Pipedream workflows, [use VPCs](/workflows/vpc).
+</Callout>
+
+If you're connecting to an app that enforces IP restrictions, you may need to whitelist the Pipedream API's IP addresses:
 
 <pre className="mt-4 nx-bg-primary-700/5 nx-mb-4 nx-overflow-x-auto nx-rounded-xl nx-subpixel-antialiased dark:nx-bg-primary-300/10 nx-text-[.9em] contrast-more:nx-border contrast-more:nx-border-primary-900/20 contrast-more:nx-contrast-150 contrast-more:dark:nx-border-primary-100/40 nx-py-4">
   {process.env.PD_EGRESS_IP_RANGE}

docs-v2/pages/destinations/http.mdx

@@ -112,13 +112,12 @@ Currently, Pipedream will not retry any failed request. If your HTTP destination
 
 ## IP addresses for Pipedream HTTP requests
 
+<Callout type="info">
+These IP addresses are tied to **requests sent with `$.send.http` only, not other HTTP requests made from workflows**. To whitelist standard HTTP requests from Pipedream workflows, [use VPCs](/workflows/vpc).
+</Callout>
+
 When you make an HTTP request using `$.send.http()`, the traffic will come from one of the following IP addresses:
 
 <PublicIPs />
 
-This list may change over time. If you've previously whitelisted these IP addresses and are having trouble sending HTTP requests to your target service, please check to ensure this list matches your firewall rules.
-
-<Callout type="warning">
-These IP addresses are tied specifically to the `$.send.http()` service. If you send traffic directly from a workflow, it will be sent from one of Pipedream's general range of IP addresses. [See our hosting docs for more information](/privacy-and-security/#hosting-details).
-</Callout>
-
+This list may change over time. If you've previously whitelisted these IP addresses and are having trouble sending HTTP requests to your target service, please check to ensure this list matches your firewall rules.

docs-v2/pages/privacy-and-security/index.mdx

@@ -22,7 +22,7 @@ If you suspect Pipedream resources are being used for illegal purposes, or other
 
 ### SOC 2
 
-Pipedream undergoes regular third-party audits. We have demonstrated SOC 2 compliance and can provide a SOC 2 Type 2 report upon request. Please reach out to <span className="font-bold">[email protected]</span> to request the latest report.
+Pipedream undergoes annual third-party audits. We have demonstrated SOC 2 compliance and can provide a SOC 2 Type 2 report upon request. Please reach out to <span className="font-bold">[email protected]</span> to request the latest report.
 
 We use [Drata](https://drata.com) to continuosly monitor our infrastructure's compliance with standards like SOC 2, and you can visit our [Security Report](https://app.drata.com/security-report/b45c2f79-1968-496b-8a10-321115b55845/27f61ebf-57e1-4917-9536-780faed1f236) to see a list of policies and processes we implement and track within Drata.
 
@@ -86,6 +86,61 @@ No credentials are logged in your source or workflow by default. If you log thei
 
 You can delete your OAuth grants or key-based credentials at any time by visiting [https://pipedream.com/accounts](https://pipedream.com/accounts). Deleting OAuth grants within Pipedream **do not** revoke Pipedream's access to your account. You must revoke that access wherever you manage OAuth grants in your third party application.
 
+## Pipedream REST API security, OAuth clients
+
+The Pipedream API supports two methods of authentication: [OAuth](/rest-api/auth#oauth) and [User API keys](/rest-api/auth#user-api-keys). **We recommend using OAuth clients** for a few reasons:
+
+✅ OAuth clients are tied to the workspace, administered by workspace admins <br />
+✅ Tokens are short-lived <br />
+✅ OAuth clients support scopes, limiting access to specific operations <br />
+
+When testing the API or using the CLI, you can use your user API key. This key is tied to your user account and provides full access to any resources your user has access to, across workspaces.
+
+### OAuth clients
+
+Pipedream supports client credentials OAuth clients, which exchange a client ID and client secret for a short-lived access token. These clients are not tied to individual end users, and are meant to be used server-side. You must store these credentials securely on your server, never allowing them to be exposed in client-side code.
+
+Client secrets are salted and hashed before being saved to the database. The hashed secret is encrypted at rest. Pipedream does not store the client secret in plaintext.
+
+You can revoke a specific client secret at any time by visiting [https://pipedream.com/settings/api](https://pipedream.com/settings/api).
+
+### OAuth tokens
+
+Since Pipedream uses client credentials grants, access tokens must not be shared with end users or stored anywhere outside of your server environment.
+
+Access tokens are issued as JWTs, signed with an ED25519 private key. The public key used to verify these tokens is available at [https:/api.pipedream.com/.well-known/jwks.json](https://pipedream.com/.well-known/jwks.json). See [this workflow template](https://pipedream.com/new?h=tch_rBf76M) for example code you can use to validate these tokens.
+
+Access tokens are hashed before being saved in the Pipedream database, and are encrypted at rest.
+
+Access tokens expire after 1 hour. Tokens can be revoked at any time.
+
+## Pipedream Connect
+
+[Pipedream Connect](/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**.
+
+### Client-side SDK
+
+Pipedream provides a [client-side SDK](/connect/api#typescript-sdk-browser) to initiate authorization or accept API keys on behalf of your users in environments that can run JavaScript. You can see the code for that SDK [here](https://github.com/PipedreamHQ/pipedream/tree/master/packages/sdk).
+
+When you initiate authorization, you must:
+
+1. [Create a server-side token for a specific end user](/connect/api#create-a-new-token)
+2. Initiate auth with that token, connecting an account for a specific user
+
+These tokens can only initiate the auth connection flow. They have no permissions to access credentials or perform other operations against the REST API. They are meant to be scoped to a specific user, for use in clients that need to initiate auth flows.
+
+Tokens expire after 4 hours, at which point you must create a new token for that specific user.
+
+### 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.
+
+Like tokens, Connect Links are coupled to specific users, and expire after 4 hours.
+
+### REST API
+
+The Pipedream Connect API is a subset of the [Pipedream REST API](/rest-api/). See the [REST API Security](#pipedream-rest-api-security-oauth-clients) section for more information on how we secure the API.
+
 ## Execution environment
 
 The **execution environment** refers to the environment in which your sources, workflows, and other Pipedream code is executed.

docs-v2/pages/rest-api/auth.mdx

@@ -1,16 +1,104 @@
 # Authentication
 
-## Pipedream API Key
+The Pipedream API supports two methods of authentication: [OAuth](#oauth) and [User API keys](#user-api-keys).
 
-When you sign up for Pipedream, an API key is automatically generated for your account. You can use this key to authorize requests to the API. 
+**We recommend OAuth** for a few reasons:
+
+✅ OAuth clients are tied to the workspace, administered by workspace admins <br />
+✅ Tokens are short-lived <br />
+✅ OAuth clients support scopes, limiting access to specific operations <br />
+
+When testing the API or using the CLI, you can use your user API key. This key is tied to your user account and provides full access to any resources your user has access to, across workspaces.
+
+## OAuth
+
+Workspace administrators can create OAuth applications in your workspace's [API settings](https://pipedream.com/settings/api). 
+
+Since API requests are meant to be made server-side, and since grants are not tied to individual end users, all OAuth clients are [**Client Credentials** applications](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).
+
+### Creating an OAuth application
+
+1. Visit your workspace's [API settings](https://pipedream.com/settings/api).
+2. Click the **New OAuth App** button.
+3. Name your app and click **Create**.
+4. Copy the app's client secret. **It will not be accessible again**. Click **Close**.
+5. Copy the app's client ID from the list of OAuth applications.
+
+### How to get an access token
+
+In the client credentials model, you exchange your OAuth client ID and secret for an access token. Then you use the access token to make API requests.
+
+If you're running a server that executes JavaScript, we recommend using [the Pipedream SDK](/connect/api#installing-the-typescript-sdk), which automatically refreshes tokens for you.
+
+```javascript
+import { createClient } from "@pipedream/sdk";
+
+// These secrets should be saved securely and passed to your environment
+const pd = createClient({
+  oauth: {
+    clientId: "YOUR_CLIENT_ID",
+    clientSecret: "YOUR_CLIENT_SECRET",
+  },
+});
+
+// Use the SDK's helper methods to make requests
+const accounts = await pd.getAccounts({ include_credentials: 1 });
+
+// Or make any Pipedream API request with the fresh token
+const accounts = await pd.makeRequest("/accounts", {
+  method: "GET"
+  headers: {
+    "Authorization": await this.oauthAuthorizationHeader(), // Automatically uses a fresh token
+  },
+  params: {
+    include_credentials: 1,
+  }
+});
+```
+
+You can also manage this token refresh process yourself, using the `/oauth/token` API endpoint:
+
+```bash
+curl https://api.pipedream.com/v1/oauth/token \
+  -H 'Content-Type: application/json' \
+  -d '{ "grant_type": "client_credentials", "client_id": "<client_id>", "client_secret": "<client secret>" }'
+```
+
+Access tokens expire after 1 hour. Store access tokens securely, server-side.
+
+### Revoking a client secret
+
+1. Visit your workspace's [API settings](https://pipedream.com/settings/api).
+2. Click the **...** button to the right of the OAuth app whose secret you want to revoke, then click **Rotate client secret**.
+3. Copy the new client secret. **It will not be accessible again**.
+
+### OAuth security
+
+See [the OAuth section of the security docs](/privacy-and-security#pipedream-rest-api-security-oauth-clients) for more information on how Pipedream secures OAuth credentials.
+
+## User API keys
+
+When you sign up for Pipedream, an API key is automatically generated for your user account. You can use this key to authorize requests to the API. 
 
 You'll find this API key in your [User Settings](https://pipedream.com/user) (**My Account** -> **API Key**).
 
+**Use user API keys when testing the API or using the CLI**. This key is tied to your user account and provides full access to any resources your user has access to, across workspaces.
+
+### Revoking your API key
+
+You can revoke your API key in your [Account Settings](https://pipedream.com/settings/account) (**Settings** -> **Account**). Click on the **REVOKE** button directly to the right of your API key.
+
+This will revoke your original API key, generating a new one. Any API requests made with the original token will yield a `401 Unauthorized` error.
+
 ## Authorizing API requests
 
-Pipedream uses [Bearer Authentication](https://oauth.net/2/bearer-tokens/) to authorize your access to the API or SSE event streams. When you make API requests, pass an `Authorization` header of the following format:
+Whether you use OAuth access tokens or user API keys, Pipedream uses [Bearer Authentication](https://oauth.net/2/bearer-tokens/) to authorize your access to the API or SSE event streams. When you make API requests, pass an `Authorization` header of the following format:
 
 ```
+# OAuth access token
+Authorization: Bearer <access token>
+
+# User API key
 Authorization: Bearer <api key>
 ```
 
@@ -24,9 +112,3 @@ curl 'https://api.pipedream.com/v1/users/me' \
 ## Using the Pipedream CLI
 
 You can [link the CLI to your Pipedream account](/cli/login/), which will automatically pass your API key in the `Authorization` header with every API request.
-
-## Revoking your API key
-
-You can revoke your API key in your [Account Settings](https://pipedream.com/settings/account) (**Settings** -> **Account**). Click on the **REVOKE** button directly to the right of your API key.
-
-This will revoke your original API key, generating a new one. Any API requests made with the original token will yield a `401 Unauthorized` error.