Suivez votre progression
Accueil Trailhead
Accueil Trailhead

Stay Secure with Access Tokens

Learning Objectives

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

  • Integrate with a Marketing Cloud 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 REST and SOAP APIs are no exception. Marketing Cloud 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 using an installed package. After you create the installed package in your Marketing Cloud 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 resources. Let’s walk through creating an installed package and finding your endpoints.

Note

Note

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

Create an Installed Package

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

  1. In Marketing Cloud, go to Setup.
  2. Click Apps.
  3. Click Installed Packages.
  4. Click New.
  5. Give the package a name and description.
  6. Create the package with enhanced functionality.
  7. Save the package.
  8. Under Components, click Add Component and select API Integration.
  9. Select an integration type.
    • Server-to-Server with Client Credentials Grant Type
    • Web and Public App Integrations with Authorization Code Grant Type
  10. 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.
  11. 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 account contains the information you need to implement your endpoints. If you can’t directly access the account, contact your Marketing Cloud 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 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 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. A web app can securely store a client secret, but a public app cannot.

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

Include code in your app to perform the redirect to the Marketing Cloud 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 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.

Resources