Connect to the Salesforce 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. The Data Cloud API has strict authentication requirements compared to other REST-based Salesforce APIs.

You can 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. These procedures show how to create a self-signed certificate.

  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. When prompted to enter information about the certificate, enter the appropriate details, 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.

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

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

You can simplify the JWT encoding process by using 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, you can skip the process of encoding the JWT and requesting a bearer token. On the Variables tab for the parent folder in the collection, populate the loginUrl, clientId, userName, and privateKey fields with your own values, which you obtained in the preceding steps. Next, send any request to the Data Cloud API. When you send a request, a pre-request 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.

The response object includes several pieces of information.

  • The access token
  • The permission scope for the token
  • Your tenant-specific API URL
  • An identity URL that can be used to identify the user
  • The token type, which 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.

The response includes an instance URL and an access token. You use both of these values to issue subsequent requests to the Data Cloud API.

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

An easy way to test your authentication token is to issue a GET call to the /api/v1/metadata/ endpoint.

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

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

This Python code example encodes a JWT based on your client ID, username, and private key. It then issues a request to the /services/oauth2/token endpoint, passing the JWT in the body of the request. The resulting output contains the bearer token, which you use to authenticate subsequent requests to the API.

To run this example, install the requests library and the PyJWT library with added cryptography support. You can install these libraries using pip.

Next, create an environment variable called CLIENTID_DC that contains your client ID (also referred to as your consumer key), and create another environment variable called USER_DC that contains your user ID.

Finally, change the value of the keyFile variable in the main function to refer to your RSA private key.

The response object includes the access token.