Setting Up Salesforce OAuth for Pardot API Authentication

Introducing Salesforce OAuth Flows for API authentication

In the Summer ’20 Release, Pardot added a more modern, consistent, and secure method for authenticating to the Pardot API. The newly supported authentication method allows customers to leverage the familiar Salesforce OAuth flows using your Salesforce users, no longer requiring a one-off Pardot only user. Yay, less context switching!

If you have current API integrations, please pay close attention since we are asking you to migrate to this new authentication by the Spring ’21 release as part of the Pardot User Migration initiative. The initiative’s overall goal is to increase security to protect your data and enable your admins to manage all users from one location – no longer needing to hop around to effectively manage your user base.

In the following sections, we’ll show you everything you need in order to leverage this new authentication method:

• Setup a connected app for your integration
• Details to gather to implement the integration
• Setting up an OAuth Flow
• Modifying your Pardot requests to leverage Salesforce OAuth
• Tips and best practices

Setting up a connected app

A connected app is a framework that enables an external application to integrate with Salesforce using APIs and standard protocols like OAuth. Connected apps use these protocols to authenticate, authorize, and provide single sign-on (SSO) for external apps. To put it simply, a connected app is a representation of an external application integration.

To set up a connected app, you will need to have Salesforce admin access to follow these steps:

1. Go to the Gear Icon > Setup
2. Type in “App Manager” in the settings search bar and select “App Manager”
3. Select “New Connected App”
4. 
5. Enter the name for your connected app (i.e. integration name)
6. Enter contact details for the owner of the connected app
7. Check the “Enable OAuth Flows” box in the API section
8. Enter a “Callback URL”, which will instruct where to redirect browser-based flows after authentication
   1. If just using for system-to-system, then it’s recommended to just enter “login.salesforce.com” since it does not really come into play
9. Under “Selected OAuth Scopes”, add the “Access Pardot services” scope which gives the app access to Pardot
10. 
11. Click “Save”

Woot, woot! You just configured your first connected app. The above setup just scratches the surface of connected apps. If you’d like to learn more, like how to restrict access to certain users, then we recommend reviewing the following resources:

• Connected App Salesforce Help
• Connected App Trailhead

Details to gather to implement the integration

Now that you have a connected app, let’s gather the details that will be needed for integration.

The primary details are:

• Connected App Consumer Key – A unique identifier for your connected app.
• Connected App Consumer Secret – Shh! It’s a secret. Essentially a password for the connected app.
• Business Unit (BU) IDs – Since a Salesforce Org may have multiple Pardot BUs, the Business Unit ID routes the API request to the correct Pardot Business Unit for your use case.
• Salesforce User Credentials with Pardot admin rights – A user will be required for testing and it would be awesome of you to have that ready to go from the start.

Since the above information is sensitive, please consider how to securely share these details with other team members.

To find the Consumer Key & Secret, follow these steps:
Note: If you just completed the “Setup a Connected App” section, then you can just click “Continue” on the post-save screen and skip to step four.

1. Go to the Gear Icon > Setup
2. Type in “App Manager” in the settings search bar & select “App Manager”
3. Go to your connected app and select “View”
4. Record your consumer key
5. Click “Click to reveal” to show and record your consumer secret

To find the Pardot Business Unit, follow these steps:

1. Go to the Gear Icon > Setup
2. Type in “Pardot Account Setup” in the settings search bar & select “Pardot Account Setup”
3. Record the business unit ID(s) for the Pardot instance you plan to integrate via the API

For the integration user, we recommend creating a unique user for each specific app integration.

Setup your OAuth Flow in your integration

Salesforce provides many different OAuth flows to meet your specific security and integration needs. We’re going to show you an example leveraging the Web Server OAuth flow. This flow is great when you want the end-user to enter their credentials to authorize the integration and you don’t want to store the credentials on your system since it could be a security risk. To learn more about the options and find the best one for your integration, please refer to Salesforce OAuth Help Documentation.

In order to use Web Server OAuth flow:

• Have your website direct the user to Salesforce’s OAuth authorize endpoint (client_id is your connected app consumer key):

https://login.salesforce.com/services/oauth2/authorize?response_type=&client_id=3MVG9IHf89I1t8hrvswazsWedXWY0i1qK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&redirect_uri=https://my.example.com/myapp&scope=pardot_api


• If the user is not logged in to Salesforce, the user is asked for credentials.
• If the user has not allowed this app previously, the user is informed that the app will be able to access Pardot data and the user has the choice to allow the app to do so.
• Once the user has logged in and allowed the app, Salesforce redirects the user back to the redirect_uri passed in to the authorize endpoint:

https://my.example.com/myapp?code=aPrx4sgoM2Nd1zWeFVlOWveD0HhYmiDiLmlLnXEBgX01tpVOQMWVSUuafFPHu3kCSjzk4CUTZg==

• Your server side code should exchange this code for an access token by making a POST request to the Salesforce OAuth token endpoint (client_secret is your connected app consumer secret):

POST /services/oauth2/token HTTP/1.1
Host: login.salesforce.com
Content-type: application/x-www-form-urlencoded
grant_type=authorization_code&
code=aPrxhgZ2MIpkSy0aOdn07LjKFvsFOis6RGcWXz7p8JQCjcqfed5NQLe7sxWwMY_JQFuLwHRaRA==&
client_id=3MVG9IHf89I1t8hrvswazsWedXWY0iqK20PSFaInvUgLFB6vrcb9bbWFTSIHpO8G2jxBLJA6uZGyPFC5Aejq&
client_secret=*******************&
redirect_uri=https://my.example.com/myapp

• After Salesforce validates the connected app credentials and authorization code, the endpoint responds with an access token:

{
"Access_token": "00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK",
"signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "pardot_api",
"instance_url": "https://example.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC",
"token_type": "Bearer",
"issued_at": "1558553873237"
}

• The access token can now be used to make calls to the Pardot API as described below. Note that because the code was exchanged for the access token on the server side and not from the user’s browser, there’s no opportunity for malicious Javascript code to steal the access token.

Configure your Pardot requests to leverage Salesforce OAuth

Now that you’ve set up and executed your authentication flow, you should have an access token. To update your Pardot request there are just two small header changes to make:

• Change your authorization header to have the value “Bearer <insert_bearer_token>”, inserting the bearer token value you received from your authorization request.
• Add the key “Pardot-Business-Unit-Id” to the header and set the value to the business unit you want to access.

curl --location --request POST 'http://pi.demo.pardot.com/api/prospect/version/4/do/query?format=json' \--header 'Authorization: Bearer 00DB0000000TfcR!AQQAQFhoK8vTMg_rKA.esrJ2bCs.OOIjJgl.9Cx6O7KqjZmHMLOyVb.U61BU9tm4xRusf7d3fD1P9oefzqS6i9sJMPWj48IK' \--header 'Pardot-Business-Unit-Id: 0UvB0000000TN1tKAG' \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'id=7676'

Once those changes are done, you can do some regression testing and then raise your hands in success for migrating your Pardot API to leverage Salesforce OAuth. Well done!

Tips and best practices

Below are some helpful tips and best practices to help make your integration go smoothly.

• Review the different Salesforce OAuth flows to determine which one is the best fit for your integration. Which OAuth flow to use is the singular most important and impactful decision to make.
• If you are leveraging a third-party integration to Pardot, then please reach out to the provider to confirm their migration plans. Depending on the provider, they may provide a connected app for you to install or may expect you to set up the connected app.
• As the Pardot endpoint header may change in the future, consider storing it somewhere in your Pardot integration code. Then reference it in each endpoint, so you can change it easily in one place.
• If you have integrations that span Pardot and Sales Cloud, then consider just using one connected app to help remove complexity. The connected app framework allows you to add multiple scopes enabling access to both Pardot and Sales Cloud endpoints using the same authentication.
• For best traceability, consider leveraging a unique user per integration. Having a different user per integration makes it easier to see what traffic is being created by which integration.
• Review the supplemental help documentation to see what other features the connected app framework provides. A few items you may want to consider: restricting the users who can access a connected app, restricting the IPs that can authenticate to an app, and learning how to remove access in case an integration becomes a problem.

Summary

Hopefully, you now feel confident in updating your Pardot API integrations to leverage Salesforce OAuth flows and creating new integrations that use them as well. More importantly, you now have more knowledge to help prepare for the Pardot User Migration due by the Spring ’21 release. I also recommend learning more about all the great Connected App capabilities and Salesforce OAuth options as there’s a lot we couldn’t cover in this blog.

About the authors

Noshir Patel is a Pardot Lead Software Engineer. He focuses on developing Pardot’s API framework and lead the Salesforce OAuth integration. You can follow him on LinkedIn.

Christopher Cornett is a Pardot Senior Product Manager. He focuses on API & Web Tracking capabilities. You can follow him on LinkedIn.