Back to main page

Instructions designed for use in the Postman's desktop app v8.

Installing the Collection

• Download Postman
• Create Private Public Key Pair
• Connected App Setup
• App Authorization
• Fork the Collection
• Configure the Collection
• Execute a Request

Postman Application

Desktop App
Download and install the Postman app from Postman.

Web App
Not currently supported. Please use the desktop application.

Note: These instructions are designed for use in the Direct APIs which are the
recommended approach for invoking the CDP APIs. If you are going to be using the
Connect APIs some steps such as the Key Pair, Connected App Setup, and App
Authorization will not be required.

Create Private Public Key Pair

1. You’ll need a .key and a .crt file (private and public key)

2. Open Terminal and change directories to any folder and run the following
commands

3. openssl genrsa 2048 > host.key

4. chmod 400 host.key
 5. openssl req -new -x509 -nodes -sha256 -days 365 -key host.key -out host.crt
Note: There will be a series of questions (Country, State, Org Name, etc) you
need to complete.

This creates a host.key and host.crt files in that folder. These will be used later in
the setup.

Connected App Setup

This collection utilizes Salesforce's server to server JWT bearer flow for acquiring an
access token. This portion of the setup will walk you through setting up the connected
app.

1. Login to Salesforce → Setup and Search "App Manager"

2. In the Setup’s Quick Find search "App Manager"

3. Select “New Connected App”

i. Connected App Name: CDP API

 ii. API Name: CDP_API (or whatever default value is prepopulated)

iii. Contact Email: Your email address

iv. Under API Heading, check the box for “Enable OAuth Settings”

v. Callback URL: https://oauth.pstmn.io/v1/callback

vi. Select the checkbox for “Use digital signatures”

vii. Select “Choose File” and select the host.crt file created in Create Private
Public Key Pair section

viii. Under “Selected OAuth Scopes” move the following from the “Available
OAuth Scopes” to “Selected OAuth Scopes”

a. Manage user data via APIs (api)

b. Perform requests at any time (refresh_token, offline_access)
c. Perform ANSI SQL queries on Salesforce CDP data (cdp_query_api)
d. Manage Salesforce CDP profile data (cdp_profile_api)
e. Manage Salesforce CDP Ingestion API data (cdp_ingest_api)
f. Note: feel free to select others if needed.

Your screen should look similar to this

ix. Select Save (on the next screen select Continue)

 x. Make note of the Consumer Key and Consumer Secret values. This will
be used as the “clientId” and “clientSecret” variables in the Postman
collection.

4. At the top of your newly created connected app click “Manage”

i. Select “Edit Policies”

ii. Change “IP Relaxation” to “Relax IP restrictions”
iii. Select Save

App Authorization
At this point your connected app has been configured however there is a one time
setup requirement to authorize your user with the connected app.

The URL format will look like:

<YOUR_ORG_URL>/services/oauth2/authorize?response_type=code&client_id=<YOUR_CONSUMER_
KEY>&scope=api refresh_token cdp_profile_api cdp_query_api
cdp_ingest_api&redirect_uri=https://oauth.pstmn.io/v1/callback
Notice the scope parameter in the above URL. It’s important that you select all the
required custom CDP scopes in this request. All further JWT bearer flow requests will
honor ONLY these scopes

YOUR_ORG_URL is the fully qualified instance URL.

YOUR_CONSUMER_KEY is the consumer key noted in step 4.x above.

Example URL:

https://aaroncates-20214005-
demo.lightning.force.com/services/oauth2/authorize?response_type=code&client_id=as
dlfjasldfjsaldfjaslfds&scope=api%20refresh_token%20cdp_profile_api%20cdp_query_api
%20cdp_ingest_api&redirect_uri=https://oauth.pstmn.io/v1/callback

1. Paste that URL in a browser window.

2. This prompts a consent dialog asking permission for each of the scopes
requested above. Select Allow and you should be redirected back.
3. You may also get an alert from the callback. If you do, select Open Postman
 4. Optional: If you want to verify everything is authorized correctly, in the Quick
Find search for “Connected Apps OAuth Usage”. Here you will see your
connected app and should see a user count of 1.

Fork the Collection

Fork the collection using the following button or follow the instructions listed below.

Option 1:

Option 2:

1. In Postman, click on the top search bar and type Salesforce

2. Click Salesforce Developers under Teams

 3. Click the Salesforce CDP/Data cloud APIs tile

4. Click Fork

5. Enter a label for your fork (e.g.: “My fork”)

6. Select a workspace (the default “My Workspace” workspace is fine)

7. Click Fork Collection

Configure the Collection

The collection uses a series of collection variables to help streamline your calls. To
successfully use the package it's important to be sure to update the collection variables.

1. Click Salesforce CDP APIs

2. Open the Variables tab
3. Complete the following variables for your instance by placing the values in
the Current Value column.
 Use Used
d In In
Variable Example Value Description Dire Conn
ct ect
APIs APIs

Using
login.salesforc
e.com will be
loginUrl login.salesforce.com X X
fine unless you
are using a
sandbox.

Salesforce API
version 52.0 version X
number

Consumer key
3MVG9l2zHsylwlpR6H5xByqIHvF from the
clientId X X
bLVATgzkY... connected
app.

Consumer
clientSecr 775C20434DB475FC326765353A secret from
X
et F5210D4... the connected
app.

-----BEGIN RSA PRIVATE KEY-----

MIIEpAIBAAKCAQEA6spOAo1Nh
TsOhj19M
privateKe Contents of
... X
y host.key file.
rEOBZ458a3O4EOfHP1luZb4ZGrn
TDRcA==
-----END RSA PRIVATE KEY-----
 Use Used
d In In
Variable Example Value Description Dire Conn
ct ect
APIs APIs

User Name of
aaroncates@aaroncates-
userName the authorized X X
20210405.demo
user.

Password of
password superSecretPassword1! the authorized X
user.

Salesforce
security token
for the
securityTo authorized
fVhwzeDFMrAh4IC9hS X
ken user. Details
for securing a
token
available here.

4. Click Save.
Collection Authentication
Direct APIs

The collection is built to leverage the OAuth 2.0 JWT Bearer Flow for Server-to-Server
Integration for Salesforce Core authorization. The core token is then exchanged with the
off core server hosting CDP for a final authorization token.

NOTE: To simplify the use of the the collection this authorization process has been
configured to run automatically prior to each request and check if a valid token
exists.
This is accomplished by using the collection variables defined in the Configure the
Collection section combined with a pre-request script.

The script creates six new variables that are used for token generation and should not
be edited:

• dne_cdpTokenRefreshTime
• dne_cdpAssertion
• dne_cdpAuthToken
• dne_cdpInstanceUrl
• dne_cdpOffcoreToken
 • dne_cdpOffcoreUrl

The Marketing Cloud authorization tokens are valid for 2 hours therefore when a token
is requested we create a new variable called dne_cdpTokenRefreshTime that stores the
time the token was generated. Each subsequent call will use this refresh time to
determine if a new token should be requested.

The token returned in the authorization call is stored as the collection

variable dne_cdpOffcoreToken and passed in the authorization header defined by a
pre-request script at folder level.

Connect APIs

The connect APIs leverage the traditional Salesforce authentication request process. You
must first run the Auth Request first and we leverage Postman's tests functionality to
parse the response body and set the variables
for dne_cdpAuthToken and dne_cdpInstanceUrl that are used in the remaining Connect API
calls.

Execute a Request
1. Expand the collection and select the Profile API -> Metadata - DMO request
2. Click Send

Note: Please on “Follow Authorization header” in setting tab.

At this point, if your environment is correctly set up, you should see a 200 OK status. This
means that you have successfully authenticated with Salesforce CDP and that you can
now use the other collection’s requests.
See additional documentation for more information on how to keep the collection up to
date and work with multiple Marketing Cloud instances.

Now we are good to use Query API

1. Expand the collection and select the Salesforce data cloud API -> Direct API ->
Query API -> Query.
2. Please on “Follow Authorization header” in setting tab.
3. Add SQL query in Body tab with {“SQL query” }
4. Use Post method to send request (api/v1/query).