SAP Engagement Cloud - Beta Developer Tooling

Please note that SAP Engagement Cloud is in the 'closed beta' phase, with general availability expected in the near future.

Written in the Postman format and tested with Bruno

This document describes the SAP Engagement Cloud Suite API v3, which uses OpenID Connect (OAuth 2.0 client credentials grant) authentication.

• Introduction to SAP Engagement Cloud API: link
• Creating your API credentials: link

For an open source alternative to Postman, this collection is also compatible with Bruno, as described here.

Creating your API user

To create your API user, follow this documentation guide for OpenID Connect

Note

Be sure to copy your all of the credential details from the gray text boxes to a secure location immediately, as you won't be able to access them again!

Using with Postman

Installing the collection in Postman

1. First, make sure you have Postman installed. These collections are meant to be used with the program Postman, which can be downloaded here: https://www.postman.com/downloads/
2. Download this repository by clicking on the Green "Code" button at the top of this page, then "Download Zip":
3. Extract the files from the .zip folder
4. With Postman installed and the collections downloaded, click on the import button in the top-left:
5. Select The upload files option:
6. Select the file "SAP Engagement Cloud Postman Collection" from the downloaded files
7. Finally, select the import button to confirm and the package will be fully installed!

Setting up your API user in Postman

1. In Postman, click on the folder for the SAP Engagement Cloud API collection, then select the Authorization tab

2. Scroll down to the "Configure New Token" section where you will see red text in the boxes for Client ID and Client Secret

3. Hover your mouse over the red text for {{OIDC_ClientID}} to see the options of where to store this variable. Click the Environment section to save the variable. If you see text that says "No environment selected", click "Create One" and give it a name like "SAP Engagement Cloud environment"

   

4. In the "Enter Value" checkbox, enter the value you saved from the SAP Engagement Cloud API user creation screen. Do this for Client ID and Client Secret. The text for each will turn from red to blue once it's configured correctly Note If you are using SAP Cloud Identities to manage your SAP Engagement Cloud API credentials, you will need to replace the Access Token URL as well

5. Scroll to the bottom of the window and click the Orange "Get New Access Token" button. Postman will take a moment to make sure your credentials work, then report it was successful. Click "Proceed" on this window, then click "Use Token"

6. Your credentials are now configured!

Configuring your Base URL

In the SAP Engagement Cloud, you will need to specify the API endpoint that your account uses for your requests. During the beta, that endpoint will always be https://api.sap.emarsys.net/api. In the future, you will be able to find it in the same page as your API users' permissions.

Here's how to set the endpoint in your environment:

1. Find out your endpoint (https://api.sap.emarsys.net/api will always be the correct endpoint while in Beta)
2. Click on the Environments dropdown in the top-right corner of Postman (it will display the name of your current environment if you have one selected)
3. Click the arrow icon next to the evironment you'd like to use, or click the 'plus' button next to the search bar to create a new one
4. Type "baseUrl" into the Variable column where it says "Add Variable" and for the value, paste your endpoint found in step 1.

Your environment should look like this:

Once your API user and base url are configured as explained above, you're ready to start using the Postman collection!

Using this collection with Bruno

Bruno is an open-source API tool that is very similar to Postman, but is fully free to use and is supported by the Open-Source community.

Installing the collection in Bruno

1. Make sure you have Bruno installed. You can download Bruno here: https://www.usebruno.com/downloads

2. Download this repository by clicking on the Green "Code" button at the top of this page, then "Download Zip":

   

3. Extract the files from the .zip folder

4. With Bruno downloaded and the collections downloaded, click on the Import Collection button:

   

5. Select "Postman Collection" for the collection type

6. Select the file "sap_engagement_cloud_postman_collection.json" from the files you downloaded previously and press open:

   

7. Bruno will then ask you where you'd like to save the imported collection. Select any location on your computer you would like to store your work in Bruno. A good option may be your Documents folder, or a project folder where you keep your work on SAP Engagement Cloud. After you do so, the API collection will be visible in Bruno.

8. Begin setting up your authentication to the API by clicking on the name of the collection in the left-hand menu and then selecting the tab "Auth". In that page, apply the following settings:

   • Set the "Grant Type" dropdown to "Client Credentials"
   • Set the Access Token URL to "https://auth.emarsys.net/oauth2/token"
   • Set the Client ID to {{OIDC_CLIENT_ID}}
   • Set the Client Secret to {{OIDC_SECRET}}
   • Set the "Add Credentials to" dropdown to "Basic Auth Header"
   • Lower down, in the Settings section, check the box for "Automatically fetch token if not found"
   • Click "Get Access Token" to test the settings
   • Click Save

   

9. Bruno is now configured and ready for you to fill in your API credentials. Follow the steps for configuring your environments in the next section before sending your first request

Setting up your API user in Bruno

This collection uses Bruno Environment Variables to manage the credentials for the account(s) you work with. This guide goes over how to create those environments

The required variables are:

• OIDC_CLIENT_ID
• OIDC_SECRET
• baseUrl

The baseUrl variable is the endpoint for API requests, which will always be https://api.sap.emarsys.net/api during the beta.

In the Engagement Cloud edition of the SAP Engagement Cloud APIs, you will need to specify the API endpoint that your account uses for your requests. During the beta, that endpoint will always be https://api.sap.emarsys.net/api. In the future, you will be able to find it in the same page as your API users' permissions.

Note

If you are using SAP Cloud Identities to manage your SAP Engagement Cloud API credentials, you will need to add your Access Token URL in the variable "OIDC_SCI_HOST"