Danny/connect proxy macro docs (#15602)

* Adding refs to proxy macros

* Update pnpm-lock.yaml

* Update pnpm-lock.yaml

* Update api-proxy.mdx

* Update api-proxy.mdx

* Update api-proxy.mdx

* Update api-proxy.mdx

Author: dannyroosevelt

docs-v2/pages/connect/api-proxy.mdx

@@ -33,7 +33,45 @@ You can send requests to the Connect proxy using the [Pipedream SDK](/connect/sd
 
 Refer to the full Connect API [here](/connect/api).
 
-### Using the Pipedream SDK (preferred)
+### Authenticating on behalf of your user
+
+Most API integrations that use OAuth to authenticate requests require that you pass a user's access token in the `Authorization` header with the `Bearer` prefix. For these apps, the Connect proxy will automatically handle that for you — you don't need to pass any reference to their OAuth access token in this case.
+
+For apps that require a different authentication method, you should include the necessary headers with the value surrounded by `{{ }}` in your request to the proxy, and Pipedream will automatically replace the macro with the real values and forward to the downstream API. For example:
+
+```javascript
+/*
+OpenAI requires that you pass the API key 
+in the `Authorization` header with the `Bearer` prefix:
+*/
+
+headers: {
+  authorization: "Bearer {{api_key}}", 
+}
+
+// Pipedream will replace the `{{api_key}}` macro with the actual API key
+```
+
+```javascript
+/*
+Zoho apps require that you pass the OAuth access token
+in the `Authorization` header with a custom `Zoho-oauthtoken` prefix:
+*/
+
+headers: {
+  authorization: "Zoho-oauthtoken {{oauth_access_token}}", 
+}
+
+// Pipedream will replace the `{{oauth_access_token}}` macro with the actual token
+```
+
+<Callout type="info">
+Refer to the relevant API's developer documentation for the correct way to authenticate requests.
+</Callout>
+
+### Making a request
+
+#### Using the Pipedream SDK
 
 You can use the [Pipedream SDK](https://www.npmjs.com/package/@pipedream/sdk) to send a fetch-style request:
 
@@ -61,8 +99,8 @@ const resp = await pd.makeProxyRequest(
     url: "https://slack.com/api/chat.postMessage", // Include any query params you need; no need to Base64 encode the URL if using the SDK
     options: {
       method: "POST",
-      headers: {
-        hello: "world!" // These get sent to the downstream API
+      headers: { 
+        hello: "world!" // Include any headers you need to send to the downstream API
       },
       body: {
         text: "hello, world",
@@ -76,7 +114,7 @@ const resp = await pd.makeProxyRequest(
 console.log(resp);
 ```
 
-### Using the REST API
+#### Using the REST API
 
 You can also send a request to the Connect REST API with the below config:
 
@@ -97,9 +135,15 @@ You can also send a request to the Connect REST API with the below config:
 
 - If using the REST API, include the `Authorization` header with your Pipedream OAuth access token (`Bearer {access_token}`)
 - Headers that contain the prefix `x-pd-proxy` will get forwarded to the downstream API
+- If the downstream API requires [custom authorization headers](#authenticating-on-behalf-of-your-user), make sure to prepend with `x-pd-proxy` and include the macro `{{ }}` that Pipedream will replace with the actual value. For example,
+
+```javascript
+"x-pd-proxy-apiKey: {{api_key}}"
+```
 
 ```bash
-# First, obtain an OAuth access token
+# First, obtain an OAuth access token to authenticate to the Pipedream API
+
 curl -X POST https://api.pipedream.com/v1/oauth/token \
   -H "Content-Type: application/json" \
   -d '{
@@ -119,4 +163,8 @@ curl -X POST "https://api.pipedream.com/v1/connect/{your_project_id}/proxy/{url_
   }'
 
 # Parse and return the data you need
-```
+```
+
+## Rate limits
+
+The Connect proxy limits API requests to **100 per minute per project**. [Let us know](https://pipedream.com/support) if you need higher limits.

docs-v2/pages/connect/api.mdx

@@ -147,7 +147,8 @@ External User IDs are limited to 250 characters.
 | API Endpoint               | Rate Limit                                           |
 |----------------------------|------------------------------------------------------|
 | `POST /tokens`   | 100 requests per minute per `external_user_id`            |
-| `GET */accounts/*`| The sum of requests across all `*/accounts/*` endpoints must not exceed 100 requests per minute. This includes requests to `/accounts`, `/apps/:app_id/accounts`, `/accounts/:account_id`, and more — any request for account metadata and credentials is counted towards this total. |
+| `GET /accounts`| 100 requests per minute per project <br /><br />The sum of requests across all `*/accounts/*` endpoints must not exceed 100 requests per minute. This includes requests to,<br />• `/accounts`<br />• `/apps/:app_id/accounts`<br />• `/accounts/:account_id` |
+| `/proxy` | 100 requests per minute per project |
 
 If you need higher rate limits, please [reach out](https://pipedream.com/support).
 

docs-v2/pages/connect/managed-auth/oauth-clients.mdx

@@ -21,9 +21,10 @@ For any OAuth app that supports it, **you can always use your own client.** Your
 <div className="highlightHeaderRowTable">
 | Operation | Details | Environment |
 |--------|---------|------------------------------|
-| [Retrieve credentials via API](/connect/api#accounts) | Fetch the credentials for your end user from Pipedream's API to use in your application. | ✅ `development`<br />❌ `production` |
-| [Invoke workflows](/connect/workflows) | Trigger any Pipedream workflow and use the connected account of your end user | ✅ `development`<br />❌ `production` |
-| [Run components via API](/connect/components) | Run any action and deploy any trigger directly from your application | ✅ `development`<br />✅ `production` |
+| Retrieve user credentrials | [Fetch the credentials](/connect/api#accounts) for your end user from Pipedream's API to use in your app | ✅ `development`<br />❌ `production` |
+| Invoke workflows | [Trigger any Pipedream workflow](/connect/workflows) and use the connected account of your end users | ✅ `development`<br />❌ `production` |
+| Embed prebuilt tools | [Run any action and deploy any trigger](/connect/components) directly from your AI agent or app | ✅ `development`<br />✅ `production` |
+| Proxy API requests | [Write custom code to interface with any integrated API](/connect/api-proxy) while avoiding dealing with user auth | ✅ `development`<br />✅ `production` |
 </div>
 
 ## Using a custom OAuth client