Stay Secure with Access Tokens

Learning Objectives

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

Integrate with a Marketing Cloud Engagement API securely.
Use access tokens for both REST and SOAP APIs.
Know when to refresh your tokens.

Get Your Token

At Salesforce, we take security seriously. And the Marketing Cloud Engagement REST and SOAP APIs are no exception. Marketing Cloud Engagement provides tenant-specific endpoints to help secure your API requests (more on this in a minute). Plus, you’re required to use OAuth tokens to access these endpoints.

To get those endpoints and tokens, you need to do a few things. Both the REST and SOAP APIs require an API integration with Marketing Cloud Engagement using an installed package. After you create the installed package in your Marketing Cloud Engagement account, you can request an access token using your client ID and secret. Any application that you create extracts that token and uses it to gain access to Marketing Cloud Engagement resources. Let’s walk through creating an installed package and finding your endpoints.

The examples in this unit use the REST API—since it’s the preferred way to interact with Marketing Cloud Engagement.

Create an Installed Package

Marketing Cloud Engagement uses installed packages to help authenticate users and API requests. For this step, you need access to your Marketing Cloud Engagement account. (Contact your Marketing Cloud Engagement admin for help.)

In Marketing Cloud Engagement, go to Setup.
Click Apps.
Click Installed Packages.
Click New.
Give the package a name and description.
Create the package with enhanced functionality.
Save the package.
Under Components, click Add Component and select API Integration.
Select an integration type.
- Server-to-Server with Client Credentials Grant Type
- Web and Public App Integrations with Authorization Code Grant Type
Set the integration properties, including scopes and the redirect URIs for web and public apps. Use https://127.0.0.1:80/ as a valid redirect URI for local testing.
Save the component.

Discover Your Endpoints

As we mentioned earlier, our APIs use tenant-specific endpoints. That means, instead of directing all requests to a single endpoint, your endpoints include a subdomain unique to your tenant. This also improves performance for your API requests by reducing the amount of traffic on any one endpoint. Faster and more secure—that’s a win-win.

Your Marketing Cloud Engagement account contains the information you need to implement your endpoints. If you can’t directly access the account, contact your Marketing Cloud Engagement admin for the information you need to get started.

Server-to-Server Integrations

Use server-to-server integrations to set up REST or SOAP API interactions between Marketing Cloud Engagement and your system. You can set up your integration in just three steps.

Step 1—Request an access token using a client ID and secret.

Installed packages generate these values for you when you create the integration. This example shows the information included in this REST API request. Store your client ID and secret securely. Never expose this information on the client side via JavaScript and don’t store it in a mobile application.

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": "email_read email_write email_send",
"account_id": "12345"
}

Step 2—Marketing Cloud Engagement returns an access token.

Extract this token for your use. Give this token the same care and protection that you do for a username and password. In other words, don’t post it on a public message board or leave it on an unencrypted document in your system.

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": "email_read email_write email_send"
}

Step 3—Access your REST and SOAP API resources.

You’re good to go! Start planning and writing your requests.

Web and Public Integrations

Use this method to allow a specific user to access your app using authorization from Marketing Cloud Engagement. A web app can securely store a client secret, but a public app cannot.

Step 1—Redirect the User Web Browser to Marketing Cloud Engagement.

Include code in your app to perform the redirect to the Marketing Cloud Engagement authorization URL for your integration. Take a look at this example.

https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com/v2/authorize?response_type=code&client_id=vqwyswrlzzfk024ivr682esb&redirect_uri=https%3A%2F%2Fwww.example.com%2Fcode_callback.jsp&scope=email_read%20email_write%20email_send&state=mystate

Step 2—Extract the authorization code.

A successful authorization returns a response containing an authorization code. Extract that code from the response, which appears like this.

https://www.example.com/code_callback.jsp?state=mystate&tssd={YOUR_MARKETING_CLOUD_SUBDOMAIN}
&code=aWekysIEeqM9PiThEfm0Cnr0MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w

Step 3—Request a token.

The request for the token looks like this.

Host: https://YOUR_SUBDOMAIN.auth.marketingcloudapis.com
POST /v2/token
Content-Type: application/json
{
   "grant_type": "authorization_code",
   "code":
"eyJhbZciOiJIUzI1NiIsImtpZCI6IjIiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJhY0tlbEVIaTdzVERNNWd5VVR1VGdsS1YiLCJjbGllbnRfaWQiOiJmaG0yd2lsb2d2ajhqNXdzcWprZmgwejUiLCJlaWQiOjEwNzcxNzA2LCJzdGFja19rZXkiOiJRQTFTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiU2VydmVyVG9TZXJ2ZXIifQ.Q0qyABvInOiz3PfGsTDbj1coVTTdD8A4pCZS395P3Qo.DoROxfr3CQlMVMtVd5gYERWFYWoiNWojKObHxOq_5BqR98CDSAqfExfH-mv3PFMzy0U2NntttdgZK5wTL0UejXCxxH_XlcgL5k1TWzv_K-uTlPmliK2eI0LnaR1ti-TSqG36RnfUWzZ8KlAuGlqdGv-wgJtLeQTCEqE97yuqnlppgLLOB",
   "client_id": "7a8j47upktedde30uedl822p",
   "client_secret": "lYkAjPxnmHP4Zarpv1U4cLf0"
   "redirect_uri": "http://www.example.com/code_callback.jsp/",
   "scope": "email_read email_write email_send offline"
}

That request prompts Marketing Cloud Engagement to return the token. Again, take the utmost care to protect this token.

HTTP/1.1 200 OK
{
"access_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJhY2Nlc3NfdG9rZW4iOiJjZ3RHRklkUjUydnY4WHhLRHZaTDU2VHAiLCJjbGllbnRfaWQiOiI5b2xhcnI3emEyZHplaWtlaTBxZ2Z0dm0iLCJlaWQiOjEwODU1ODQsInN0YWNrX2tleSI6IlFBM1MxIiwicGxhdGZvcm1fdmVyc2lvbiI6MiwiY2xpZW50X3R5cGUiOiJDb25maWRlbnRpYWwifQ.Hp6gLSnlvBsx9FI6qXwJ12HJVzStWLIJdlzrx4XIIN4.t2kCu9YBNHVask49MQZXMlKGvYMXEc50QkRTc3y5_ylEWC8hPyEkU9sIanqL0ALSwFNyhQmMF6aajnmSrsD5obIl-NjXNfIwYWmnDqZU6HFBgbMoR3ofuEGIhrGokqUbD8nHZtgp-otgQSOg5Qj_RqUHUC0N0Fo4BUCXTq5BiM_EjP_djIKZF",
"refresh_token":"eyJhbZciOiJIUzI1NiIsImtpZCI6IjEiLCJ2ZXIiOiIxIiwidHlwIjoiSldUIn0.eyJyZWZyZXNoX3Rva2VuIjoiY2JINUE0aUdnTnBQVmJzOTlCUlZnNmh6IiwiY2xpZW50X2lkIjoiOW9sYXJyN3phMmR6ZWlrZWkwcWdmdHZtIiwiZWlkIjoxMDg1NTg0LCJzdGFja19rZXkiOiJRQTNTMSIsInBsYXRmb3JtX3ZlcnNpb24iOjIsImNsaWVudF90eXBlIjoiQ29uZmlkZW50aWFsIn0.-kScEfPhdz2g75b-KgTnmYKK9YTbUu9m9AhDTKkYFr4.mFd_EyLlPeAmfmwqqiBi_0HrAL5Ndtj1R9zWMj0Y80FOjB9n_EPYR0nKGKkNeijVuxmdMNgnOSF_isxGDwqjDoor2x4B-gP9Erl0gl4u58yzAXcjesNoJ1L96HJ3kjg-Jwke4p4K1MEWoB0fsrbDUaIAkg2Tf5THwrTLAxKRhn-ANltUDwUt",
   "expires_in":1200,
   "token_type":"Bearer",
"rest_instance_url":"mc563885gzs27c5t9-63k636tzgm.rest.marketingcloudapis.com",
"soap_instance_url":"mc563885gzs27c5t9-63k636tzgm.soap.marketingcloudapis.com",
   "scope": "email_read email_write email_send"
}

Step 4—Access your REST and SOAP API resources.

Once you have your tokens in place, you’re ready to implement some REST or SOAP API requests!

Now that you can securely access both of the APIs, let’s take a closer look at each one. First up: the REST API.