API Specification Guide

Draft Document

This document is a work in progress and may change eventually.

Document Purpose

This document serves as a technical guide for developers, offering a comprehensive overview of accessing Data Cloud APIs. It includes each API's purpose, authentication methods, and field-level details to support efficient integration and data management.

Prerequisites

Authentication

Users must authenticate to the system using the provided client credentials to obtain an access token. This token is required for making API requests. To authenticate and retrieve the token, follow these steps:

1. Make a POST request to the following URL:

   https://<authorization fqdn>/oauth2/token

2. Set the request headers:

   Content-Type: application/x-www-form-urlencoded

3. Include the following data in the request body:

   1. grant_type=client_credentials

   2. client_id=<client_id>

   3. client_secret=<client_secret>

4. Send the request.
   The response includes the access token, which must be used in the API calls to Data Cloud.

   Sample Cognito Request

   POST /oauth2/token HTTP/1.1
   Host: <authorization fqdn>/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

   Sample Response

   {
     "access_token": "eyJraWQiOiI0NjB0T1d6aGR0UzhnbzNINnk0TmRGeTJKWkF1dUtcLzNwYXk1SElOa0hSdz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1Y2U4bGptczdqYnU1YTYzMzV0bjdycDljOSIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYWNxdWVvblwvMTQwMDAwMTQ3LTE5NyIsImF1dGhfdGltZSI6MTczMjUyMTQzNSwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLnVzLWVhc3QtMS5hbWF6b25hd3MuY29tXC91cy1lYXN0LTFfcERZdG5qdzdqIiwiZXhwIjoxNzMyNTI1MDM1LCJpYXQiOjE3MzI1MjE0MzUsInZlcnNpb24iOjIsImp0aSI6ImU1Nzc1NGM4LWI3OWQtNDI1Zi1iNjRmLWY1MmI4YjQ4YmQ1ZiIsImNsaWVudF9pZCI6IjVjZThsam1zN2pidTVhNjMzNXRuN3JwOWM5In0.C2bEKNjdbIlugWMXO_XynRKvCAiBauna-ViqeX_Tb03eFNH5YY95oF6i_uDGogx9BSxzSgLeTdeXOq6ZUxZDSusD4ZSLFOn5D9dOT4mdHpfpAS32dfiX1QJU_E9DATNK6ECn-_e1GvyJx2XsCsaxh_987ZbpilGqvxsonDRo5I2SKhXmepW6dAHugjYtlnTOOcMvQaIeKyLb5fkW8vqIpYy-KiTNX8G-7XdZ64P7KPuFmFE3imkGb0tuRugm_-Z5tvyXf76H_Z2zxdkIxO9ojldILGnqm5C1gsuxBWL2sel52GeNeTIp3OXrFnhgPAA2cBVqOzssNy-MHLvq8UePPA",
     "expires_in": 3600,
     "token_type": "Bearer"
   }

Important:

Once the Tenant has been configured and the Identity Provider (IdP) is set up, the following credentials are obtained:

• Client ID

• Client Secret

• Fully Qualified Domain Name (FQDN)

These credentials must be filled in the respective highlighted sections above and shared with the customer for use in API requests.