Connect to Salesforce Data 360 Connect API

Data 360 Connect API is a high-performance API for ingesting data into Data 360. You can also use it to query data and to manage calculated data insights for Marketing Cloud Next. Data 360 Connect API has strict authentication requirements compared to other REST-based Salesforce APIs.

Use Connect API to manage segments and identity resolution rulesets in Data 360. For information about connecting to Connect API, see Connect to REST-based APIs.

Note

Step 1: Generate a Private Key and Self-Signed Certificate

Interacting with Data 360 Connect API requires a signed digital certificate. You can use a private key and certificate issued by a certification authority. Alternatively, you can use OpenSSL to create a key and a self-signed digital certificate. Here’s how to create a self-signed certificate with OpenSSL.

At the command line, create a directory to store your certificate and private key.
1mkdir ~/jwt && cd ~/jwt

Create a 2048-bit RSA key.

1openssl genrsa 2048 > host.key && chmod 400 host.key

Use the private key to sign a certificate. Enter details about the certificate, or press Enter at each prompt to accept the default value.
1openssl req -new -x509 -nodes -sha256 -days 365 -key host.key -out host.crt

Step 2: Create an External Client App

An external client app is a framework that enables a third-party app to integrate with Salesforce by using APIs.

In Setup, in the Quick Find box, enter client app, and then select External Client App Manager.
Click New External Client App.
Enter an app name and your email address.
Select Enable OAuth Settings.
For Callback URL, enter http://localhost:1717/OauthRedirect.
Select Use digital signatures, and then click Browse.
Select your self-signed certificate.
Add the OAuth scopes that are necessary for your use case. For example, if your use case requires you to ingest content, add the Manage Data Cloud Ingestion API data (cdp_ingest_api) scope. Also add the Perform requests at any time (refresh_token, offline_access) scope so that you can refresh your bearer token as needed. See OAuth Tokens and Scopes.
Save your changes.
Click Manage Consumer Details.
Copy the Consumer Key value. This value is also referred to as the client ID. You use the client ID value when you encode a Java Web Token (JWT).

Step 3: Encode a JWT

Encode a JWT by completing the steps in OAuth 2.0 JWT Bearer Flow for Server-to-Server Integration.

For best results, use libraries for your preferred programming language. Popular libraries include PyJWT for Python, jwt-encode for JavaScript, or java-jwt for Java. We provide a code example that uses PyJWT to encode the JWT and request a token.

The Salesforce Data 360 Connect API Postman collection handles this step for you. In the Postman collection, on the Variables tab for the parent folder, populate the loginUrl, clientId, userName, and privateKey fields with the values that you obtained earlier. Next, send a request to the API. When you send a request, a prerequest script encodes the JWT and uses it to retrieve a bearer token. It also creates variables that track the age of the token and automatically requests a new token if the existing token is expired.

Step 4: Request an Access Token

To request an access token, issue a POST request to the login endpoint for your Salesforce instance.

1POST /services/oauth2/token HTTP/1.1
2Host: login.salesforce.com
3Content-Type: application/x-www-form-urlencoded
4
5grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
6assertion=YOUR_JWT

If the request is successful, the response object includes the access token, the permission scope, your tenant-specific API URL, an identity URL, and the token type. The value of token_type is always Bearer.

1{
2  "access_token": "00DSB0000023p85!AQEAQM2kTRKkIiXrNHHXkTOsRZPO2vCsj71esL7xxEADntI1wPENsCKOcL3mw2ag3udQYanhaKqI3smq_50XgvkiWy5NCRrx",
3  "scope": "cdp_query_api cdp_identityresolution_api cdp_ingest_api cdp_calculated_insight_api cdp_segment_api cdp_profile_api",
4  "instance_url": "https://MY_DOMAIN_LOGIN_URL",
5  "id": "https://login.salesforce.com/id/00BCM0000082q383BC/004TB0000029cmJWM42",
6  "token_type": "Bearer"
7}

Step 5: Exchange the Access Token for a Data 360 Token

Use your access token to obtain a token specifically for Data 360 by issuing a POST request to the /services/a360/token endpoint.

1POST /services/a360/token
2Host: YOUR_SUBDOMAIN.my.salesforce.com
3Content-Type : application/x-www-form-urlencoded
4
5grant_type=urn:salesforce:grant-type:external:cdp&
6subject_token=ACCESS_TOKEN&
7subject_token_type=urn:ietf:params:oauth:token-type:access_token

If the request is successful, the response includes an instance URL and an access token.

1{
2  "access_token": "DATA_CLOUD_TOKEN",
3  "instance_url": "MY_DOMAIN_LOGIN_URL",
4  "token_type": "Bearer",
5  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
6  "expires_in": 7191
7}

Use the access token to issue subsequent requests to Data 360 Connect API.

Step 6: Use the Token in Data 360 Connect API Requests

When you make subsequent calls to Data 360 Connect API, include your token as a request header that uses the bearer token syntax.

1Authorization: Bearer ACCESS_TOKEN

Test your authentication token by issuing a GET call to the /api/v1/metadata/ endpoint.

1GET /api/v1/metadata/ HTTP/1.1
2Host: MY_DOMAIN_LOGIN_URL
3Authorization: Bearer DATA_CLOUD_TOKEN

If the request is successful, the response includes information about the data model objects in your Data 360 account.

1{
2  "metadata": [
3    {
4      "fields": [
5        {
6          "name": "AccountId__c",
7          "displayName": "Account ID",
8          "type": "STRING",
9          "businessType": "TEXT"
10        },
11        {
12          "name": "AssistantName__c",
13          "displayName": "Assistant’s Name",
14          "type": "STRING",
15          "businessType": "TEXT"
16        },
17        {
18          "name": "AssistantPhone__c",
19          "displayName": "Asst. Phone",
20          "type": "STRING",
21          "businessType": "TEXT"
22        },
23        {
24          "name": "Birthdate__c",
25          "displayName": "Birthdate",
26          "type": "DATE_TIME",
27          "businessType": "DATE_TIME"
28        },
29        ...
30      ]
31    }
32  ]
33}

Authentication tokens are valid until the time specified in the JWT that you used to obtain the bearer token. To issue API requests after the bearer token expires, request a new token.