Set Up Your Developer Environment

Learning Objectives

After completing this unit, you’ll be able to:

• Explain different types of integration components.
• Create an enhanced installed package in your Marketing Cloud Engagement account.
• Obtain credentials for API integration authentication.

Did you think we’d let you finish this badge without developing something? Fear not. All your hard work learning about Marketing Cloud Engagement developer tools and admin concepts is about to pay off. In this unit, we’re walking through the steps to set up your developer environment. Then, in the next unit, you get to try out a simple project to validate your setup. 

Want to follow along with these steps in your Marketing Cloud Engagement account? You need the “Administer” permission for Installed Packages to complete the steps in this module. Talk to your Marketing Cloud Engagement administrator to get that permission enabled.

Create a Package

The first step to setting up your developer environment is to create an installed package in your Marketing Cloud Engagement account. A package is a container made up of components that create and manage custom functionality. In other words, the components determine what the package can do. 

Why create a package? You use the package to create API integrations, install custom apps, or add custom Journey Builder components for example, all of which you can share with other business units in the Marketing Cloud Engagement account. Here are a few examples of reasons to create a package:

For this test, we’re going to set up your development environment for an enhanced package. 

1. In Marketing Cloud Engagement, navigate to Setup.
2. Under Platform Tools, expand Apps and click Installed Packages.
3. Click New.
4. Give the package a name and description so that you can easily identify it as your first test package.
5. Save the package. After the package is saved, you can view the package details.
6. Under Components, click Add Component.
7. In this step, you select a component type. For our testing purposes, select API Integration.

Integration Type

Next you choose the Integration Type: Web App, Public App, or Server-to-Server. These types of integrations use the OAuth 2.0 protocol to obtain an access token. A little about each:

For our testing purposes, select Server-to-Server and click Next.

Set Properties

For the final step of adding a component, you need to set the properties. Enable the scope for the platform functions you are including within the integration. Will this API integration allow for updates to Contacts? Create new Emails? The API scope represents a grouping of permissions that ensure your API request can access the appropriate functions. The properties can also include redirect URIs for web and public apps.

For our testing purposes, ensure that Write access is enabled for both Audiences and List and Subscribers under Contacts. 

Click Save to finish your component, and give yourself a pat on the back.

Do you want to change the scope after you’ve saved? No problem. Click Edit and adjust the scope as needed. Check out REST API Permission IDs and Scopes on Salesforce Developers to understand what scopes are required for each route.

Get Credentials

Now that your package is created and your component is added, you need to identify the authentication credentials that you’ll use for your integration. Easy! When you create an API integration in Installed Packages, the Marketing Cloud Engagement authorization server generates a client ID and client secret. Check out the component for the installed package you just created. You can locate the client ID and client secret, if applicable, under the component details. 

Wondering why we blurred out the Client ID and Client Secret in the image above? You should always store your client ID and secret securely. Never expose this information on the client side via JavaScript or store it in a mobile application.

Access Tokens for Server-to-Server Integrations

In the client credentials flow, your client application uses this client ID and client secret to request an access token from the Marketing Cloud Engagement authorization server. The access token gives your application access to Marketing Cloud Engagement’s REST and SOAP services. (The client credentials grant type doesn’t have refresh tokens.) 

Here’s how it works.

1. Your application requests an access token by providing the client ID and secret that was generated for the package you created in Marketing Cloud Engagement.
2. The Marketing Cloud Engagement authorization server returns an access token for your application to extract.
3. Your application uses the access token to access Marketing Cloud Engagement resources and the REST or SOAP base URLs returned as part of the token response.

So how does your application request the access token for the server-to-server integration we’re exploring in this unit? Construct a static endpoint for your request by appending v2/token to the Authorization Base URI provided to you when you created the API integration in Installed Packages. Request an access token by providing the client ID and secret that you received when you created the API integration in Installed Packages.

When the access token expires, your application must request a new access token using the same v2/token route as before. The lifetime of an access token is 20 minutes. Here’s an example request:

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
"grant_type": "client_credentials",
"client_id": "7a9j47upktedde30uedl822p",
"client_secret": "1955278925675241571",
"scope": "list_and_subscribers_write audiences_write",
"account_id": "12345"
}

Just a reminder that in this example, the scope reflects the enabled permissions for the API request and the account ID is the MID for the account.

Marketing Cloud Engagement then returns an access token. Your application must extract the access token and store it safely. Here’s an example response:

HTTP/1.1 200 OK
{
"access_token":"eyJhbLciOiJIPzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjIifQ.eyJhY2Nlc3NfdG9rZW4iOiJhYmJUQTlpSHZqRjkyd3Jkb0xWZEFCaloiLCJjbGllbnRfaWQiOiI3ZTRmYW1xaWUzcWtzdzlhNDRrcmxvZDgiLCJlaWQiOjEwNzU3Njc2LCJzdGFja19rZXkiOiJRQTFTMSJ9.wSFfEdeNrkoiU_tnmJ2ihm8iUqnJKlZoI3GlavTGBhs.hU4EsiC1e9txh_TCt90YlI2l7xZZ5E6_oa0xku3Jj9CCk1B72M4bhO3kUIyhwfVuB0MFbL0y9KD_RRFzg-nuqPgjPyONnby-iWopdZPBHd-3woupxCMST5-vfJO9qAED9qiUfYLS4WmHRuJTCX4NPScyu8BdROTVEe-D3iAoAeFoJX_rLZ9d5eEhIn1AvkYgoj9siuxAprHEvmySTgNIXkQA6uT_IQ-H1dbfOyJmlFKpYzvhvHb0KH7NJ24zy5bd2MQ5",
"expires_in":1200,
"token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
"scope": "list_and_subscribers_write audiences_write"
}

Ready to give this a try? In the next unit, we walk through a simple Marketing Cloud Engagement project to validate your setup.

Resources

• Salesforce Developer: Access Token for Server-to-Server Integrations
• Salesforce Developer: Create an OAuth 2.0 API Integration in Enhanced Packages
• Salesforce Developer: Get Started, Marketing Cloud Engagement Developers
• Salesforce Developer: Installed Package Definitions
• Salesforce Developer: REST API Permission IDs and Scopes