Many more fixes

dylburger · dylburger · commit 72921fe21612 · 2024-10-18T15:44:28.000-07:00
diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx
@@ -591,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/
diff --git a/docs-v2/pages/connect/index.mdx b/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
 
diff --git a/docs-v2/pages/privacy-and-security/index.mdx b/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">support@pipedream.com</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">support@pipedream.com</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.
diff --git a/docs-v2/pages/rest-api/auth.mdx b/docs-v2/pages/rest-api/auth.mdx
@@ -14,7 +14,7 @@ When testing the API or using the CLI, you can use your user API key. This key i
 
 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](#how-client-credentials-apps-work).
+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
 
@@ -24,14 +24,72 @@ Since API requests are meant to be made server-side, and since grants are not ti
 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 client credentials apps work
+### 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
 
 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:
@@ -54,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.
diff --git a/docs-v2/pages/rest-api/index.mdx b/docs-v2/pages/rest-api/index.mdx
