Connect to the Data Cloud API

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

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

Interacting with the Data Cloud 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.

  1. At the command line, create a directory to store your certificate and private key.

  2. Create a 2048-bit RSA key.

  3. Use the private key to sign a certificate. Enter details about the certificate, or press Enter at each prompt to accept the default value.

A connected app is a framework that enables an external application to integrate with Salesforce using APIs. Create connected apps in the Salesforce web app.

  1. In Setup, in the Quick Find box, enter apps, and then select App Manager.
  2. Click New Connected App.
  3. For Connected App Name, enter an app name and your email address.
  4. Select Enable OAuth Settings.
  5. For Callback URL, enter http://localhost:1717/OauthRedirect.
  6. Select Use digital signatures, and then click Browse.
  7. Select your self-signed certificate.
  8. 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.
  9. Click Save.
  10. Click Manage Consumer Details.
  11. 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).

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

We recommend that you use libraries for your preferred programming language, such as 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.

If you’re using the Salesforce Data Cloud APIs Postman collection, skip the process of encoding the JWT and requesting a bearer token—the 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.

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

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.

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

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

Use the access token to issue subsequent requests to the Data Cloud API.

When you make subsequent calls to the Data Cloud API, include your token as a request header using the bearer token syntax.

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

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

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