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:
| Component |
Package Creation Reason |
|---|---|
| API Integration |
You create an integration with a third-party application, which needs access to the Marketing Cloud Engagement REST API. To get a client ID and secret, create an installed package with an API Integration component. You can have one API integration per package. |
| Marketing Cloud Engagement App |
You create an app outside of Marketing Cloud Engagement that you'd like to iFrame into Marketing Cloud Engagement. Create an installed package with a Marketing Cloud Engagement App component. You can have one Marketing Cloud Engagement App per package. If your app needs access to the Marketing Cloud Engagement API, create an API Integration component, as well. |
| Custom Content Block |
Instead of using Content Builder's CKEditor WYSIWYG for HTML editing, you'd like to use a different WYSIWYG, such as QuillJS. Create an installed package with a Custom Content Block component. |
| Journey Builder Activity |
You need a custom activity for one of your journeys that kicks off a REST API request in a third-party application. Create an installed package with a Journey Builder Activity component. You can include multiple Journey Builder Activities per package. |
| Journey Builder Entry Source |
You need a custom entry source for one of your journeys that comes via a REST API request from a third-party application. Create an installed package with a Journey Builder Entry Source component. You can have multiple Journey Builder Entry Source per package. |
For this test, we’re going to set up your development environment for an enhanced package.
- In Marketing Cloud Engagement, navigate to Setup.
- Under Platform Tools, expand Apps and click Installed Packages.
- Click New.
- Give the package a name and description so that you can easily identify it as your first test package.
- Save the package. After the package is saved, you can view the package details.
- Under Components, click Add Component.
- 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:
| Integration Type |
Description |
OAuth Grant Type |
|---|---|---|
| Web App |
Web Apps make API requests in the context of an end user. These integrations are issued a client ID and client secret because they can maintain the confidentiality of a client secret. |
Authorization Code |
| Public App |
Public Apps, such as single-page or mobile applications, make API requests in the context of an end user. These integrations are issued only a client ID because they cannot maintain the confidentiality of a client secret. |
Authorization Code |
| Server-Server |
A server-to-server integration performs tasks on behalf of the integration, without an end-user context, user interaction, or user interface.They make API requests in the context of a service account instead of a user account. These integrations are issued a client ID and client secret to use with the Client Credentials grant type. |
Client Credentials |
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.
- 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.
- The Marketing Cloud Engagement authorization server returns an access token for your application to extract.
- 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
