diff --git a/docs-v2/pages/connect/api.mdx b/docs-v2/pages/connect/api.mdx index bdea29788ce63..0a9db9a222d25 100644 --- a/docs-v2/pages/connect/api.mdx +++ b/docs-v2/pages/connect/api.mdx @@ -305,6 +305,19 @@ The ID of the [OAuth app](/connect/quickstart#create-a-pipedream-oauth-client) y [The external user ID](/connect/api/#external-users) in your system that you want to retrieve accounts for. +--- + +`include_credentials` **boolean** (_optional_) + +Pass `include_credentials=true` as a query-string parameter to include the account credentials in the response. + + +Never return user credentials to the client + + + +To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/oauth-clients#using-pipedream-oauth). + ##### Examples @@ -324,9 +337,14 @@ const pd = createBackendClient({ projectId: "{your_project_id}" }); -const accounts = await pd.getAccounts(); +const accounts = await pd.getAccounts({ + app: "github", // optional, filter by app + external_user_id: "user-abc-123", // optional, filter by external user ID + include_credentials: true, // optional, set to true to include credentials +}); -// Parse and return the data you need +// Parse and return the data you need. These may contain credentials, +// which you should never return to the client ``` @@ -342,9 +360,14 @@ const pd = createBackendClient({ projectId: "{your_project_id}" }); -const accounts = await pd.getAccounts(); +const accounts = await pd.getAccounts({ + app: "github", // optional, filter by app + external_user_id: "user-abc-123", // optional, filter by external user ID + include_credentials: true, // optional, set to true to include credentials +}); -// Parse and return the data you need +// Parse and return the data you need. These may contain credentials, +// which you should never return to the client ``` @@ -360,16 +383,31 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ # The response will include an access_token. Use it in the Authorization header below. -curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts" \ - -H "Authorization: Bearer {access_token}" +curl -X GET \ + -G \ + "https://api.pipedream.com/v1/connect/{project_id}/accounts" \ + -H "Authorization: Bearer {access_token}" \ + -d "app=github" \ # optional, filter by app + -d "external_user_id=user-abc-123" \ # optional, filter by external user ID + -d "include_credentials=true" # optional, include credentials + + +# Parse and return the data you need. These may contain credentials, +# which you should never return to the client ``` -##### Example response +##### Example response (without credentials) ```json { + "page_info": { + "total_count": 5, + "count": 5, + "start_cursor": "YXBuX0JtaEJKSm0", + "end_cursor": "YXBuX1YxaE1lTE0", + }, "data": { "accounts": [ { @@ -442,6 +480,53 @@ curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts" \ } ``` +##### Example response (with credentials) + +```json +{ + "page_info": { + "total_count": 1, + "count": 1, + "start_cursor": "YXBuX0JtaEJKSm0", + "end_cursor": "YXBuX1YxaE1lTE0", + }, + "data": { + "accounts":[ + { + "id": "apn_MGhvgnX", + "name": "gcostanza", + "external_id": "user-abc-123", + "healthy": true, + "dead": null, + "app": { + "id": "oa_aPXiQd", + "name_slug": "github", + "name": "GitHub", + "auth_type": "oauth", + "description": "Where the world builds software. Millions of developers and companies build, ship, and maintain their software on GitHub—the largest and most advanced development platform in the world.", + "img_src": "https://assets.pipedream.net/s.v0/app_OrZhaO/logo/orig", + "custom_fields_json": "[]", + "categories": [ + "Developer Tools" + ] + }, + "created_at": "2024-12-03T04:26:38.000Z", + "updated_at": "2024-12-11T17:59:28.000Z", + "credentials": { + "oauth_client_id": "xyz789...", + "oauth_access_token": "xxx_abc123...", + "oauth_uid": "123456789" + }, + "expires_at": null, + "error": null, + "last_refreshed_at": "2024-12-11T17:59:28.000Z", + "next_refresh_at": "2024-12-11T18:56:28.000Z" + } + ] + } +} +``` + #### Retrieve account details by ID Retrieve the account details for a specific account based on the account ID @@ -468,6 +553,10 @@ The ID of the account you want to retrieve Pass `include_credentials=true` as a query-string parameter to include the account credentials in the response. + +Never return user credentials to the client + + To retrieve the credentials for any account in `production` for OAuth apps (Slack, Google Sheets, etc), the connected account must be using [your own OAuth client](/connect/oauth-clients#using-a-custom-oauth-client). You can only retrieve end user credentials for accounts that are using Pipedream's OAuth clients in `development`. [Learn more here](/connect/oauth-clients#using-pipedream-oauth). @@ -491,7 +580,9 @@ const pd = createBackendClient({ }); const account = await pd.getAccountById(accountId, { - include_credentials: true, // set to true to include credentials + app: "github", // optional, filter by app + external_user_id: "user-abc-123", // optional, filter by external user ID + include_credentials: true, // optional, set to true to include credentials }); // Parse and return the data you need. These may contain credentials, @@ -514,7 +605,9 @@ const pd = createBackendClient({ const accountId = "{account_id}"; // Replace with your account ID const account = await pd.getAccountById(accountId, { - include_credentials: true, // set to true to include credentials + app: "github", // optional, filter by app + external_user_id: "user-abc-123", // optional, filter by external user ID + include_credentials: true, // optional, set to true to include credentials }); // Parse and return the data you need. These may contain credentials, @@ -534,8 +627,16 @@ curl -X POST https://api.pipedream.com/v1/oauth/token \ # The response will include an access_token. Use it in the Authorization header below. -curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts/{account_id}?include_credentials=true" \ - -H "Authorization: Bearer {access_token}" +curl -X GET \ + -G \ + "https://api.pipedream.com/v1/connect/{project_id}/accounts/{account_id}" \ + -H "Authorization: Bearer {access_token}" \ + -d "app=github" \ # optional, filter by app + -d "external_user_id=user-abc-123" \ # optional, filter by external user ID + -d "include_credentials=true" # optional, include credentials + +# Parse and return the data you need. These may contain credentials, +# which you should never return to the client ``` @@ -590,7 +691,7 @@ curl -X GET "https://api.pipedream.com/v1/connect/{project_id}/accounts/{account }, "expires_at": "2024-08-01T05:04:03.000Z", "project_id": 279440, - "user_id": "danny", + "user_id": "gcostanza", "error": null, "last_refreshed_at": null, "next_refresh_at": "2024-08-01T04:17:33.000Z" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a2e2a335e3d77..f814f24117e07 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -24489,22 +24489,22 @@ packages: superagent@3.8.1: resolution: {integrity: sha512-VMBFLYgFuRdfeNQSMLbxGSLfmXL/xc+OO+BZp41Za/NRDBet/BNbkRJrYzCUu0u4GU0i/ml2dtT8b9qgkw9z6Q==} engines: {node: '>= 4.0'} - deprecated: Please upgrade to v7.0.2+ of superagent. We have fixed numerous issues with streams, form-data, attach(), filesystem errors not bubbling up (ENOENT on attach()), and all tests are now passing. See the releases tab for more information at . + deprecated: Please upgrade to v9.0.0+ as we have fixed a public vulnerability with formidable dependency. Note that v9.0.0+ requires Node.js v14.18.0+. See https://github.com/ladjs/superagent/pull/1800 for insight. This project is supported and maintained by the team at Forward Email @ https://forwardemail.net superagent@4.1.0: resolution: {integrity: sha512-FT3QLMasz0YyCd4uIi5HNe+3t/onxMyEho7C3PSqmti3Twgy2rXT4fmkTz6wRL6bTF4uzPcfkUCa8u4JWHw8Ag==} engines: {node: '>= 6.0'} - deprecated: Please upgrade to v7.0.2+ of superagent. We have fixed numerous issues with streams, form-data, attach(), filesystem errors not bubbling up (ENOENT on attach()), and all tests are now passing. See the releases tab for more information at . + deprecated: Please upgrade to v9.0.0+ as we have fixed a public vulnerability with formidable dependency. Note that v9.0.0+ requires Node.js v14.18.0+. See https://github.com/ladjs/superagent/pull/1800 for insight. This project is supported and maintained by the team at Forward Email @ https://forwardemail.net superagent@5.3.1: resolution: {integrity: sha512-wjJ/MoTid2/RuGCOFtlacyGNxN9QLMgcpYLDQlWFIhhdJ93kNscFonGvrpAHSCVjRVj++DGCglocF7Aej1KHvQ==} engines: {node: '>= 7.0.0'} - deprecated: Please upgrade to v7.0.2+ of superagent. We have fixed numerous issues with streams, form-data, attach(), filesystem errors not bubbling up (ENOENT on attach()), and all tests are now passing. See the releases tab for more information at . + deprecated: Please upgrade to v9.0.0+ as we have fixed a public vulnerability with formidable dependency. Note that v9.0.0+ requires Node.js v14.18.0+. See https://github.com/ladjs/superagent/pull/1800 for insight. This project is supported and maintained by the team at Forward Email @ https://forwardemail.net superagent@7.1.6: resolution: {integrity: sha512-gZkVCQR1gy/oUXr+kxJMLDjla434KmSOKbx5iGD30Ql+AkJQ/YlPKECJy2nhqOsHLjGHzoDTXNSjhnvWhzKk7g==} engines: {node: '>=6.4.0 <13 || >=14'} - deprecated: Please downgrade to v7.1.5 if you need IE/ActiveXObject support OR upgrade to v8.0.0 as we no longer support IE and published an incorrect patch version (see https://github.com/visionmedia/superagent/issues/1731) + deprecated: Please upgrade to v9.0.0+ as we have fixed a public vulnerability with formidable dependency. Note that v9.0.0+ requires Node.js v14.18.0+. See https://github.com/ladjs/superagent/pull/1800 for insight. This project is supported and maintained by the team at Forward Email @ https://forwardemail.net supports-color@2.0.0: resolution: {integrity: sha512-KKNVtd6pCYgPIKU4cp2733HWYCpplQhddZLBUryaAHou723x+FRzQ5Df824Fj+IyyuiQTRoub4SnIFfIcrp70g==}