Acquia CDP

API policy

Customer Data Platform (CDP) APIs facilitate the Create, Read, Update, Delete (CRUD) operations model with specific considerations for each operation.

CRUD operations

The following are the CRUD operations:

  • Create: Create new authorization access to improve service usage and facilitate data flow into the API.

  • Read: Get access to retrieve existing authorizations. API does not support reading of records and information stored in CDP.

  • Update: API does not support the Update operation.

  • Delete: Delete the authorization access. API does not support the requests for record deletion.

Authorization

Before performing any action, you must authenticate and authorize the API request. This process ensures that the request is valid and the requester possesses the necessary permissions to execute the intended operation. The authorization mechanism inspects the request against security policies and access controls, safeguarding against unauthorized access and modifications.

Token requests

Authorization tokens secure access and ensure the integrity of interactions across the Customer Staging (CS), User Acceptance Testing (UAT) and PROD (Production) environments within CDP. These tokens are in compliance with security requirements and specific nature of each environment, with all requests characterized by "userType": "CLIENT".

Bearer token validity

Within the CS, UAT, and PROD environments, bearer tokens are essential for securing three primary types of accounts: 

  • Integration user accounts
  • Webtag service user accounts
  • 360 Profiles user accounts

The lifespan of these tokens is set as 180 days, which is explicitly reflected in the "expires_in" attribute as 15599999 seconds in the JSON response from a GET request to verify authentication access. As tokens approach expiration, you must perform token maintenance through one of following methods:

  • Extend tokens: Prolongs token's validity beyond the initial expiration.

  • Delete tokens: Deletes a token to end its validity.

  • Wipe all tokens: Removes all tokens associated with an account.

Note

Acquia does not prescribe a singular methodology for managing bearer token lifecycles. Instead, we furnish the mechanisms to align with your organization's policies. While some companies prefer an annual bearer token cycle, extending the validity well beyond the default 180 days, others opt for a more accelerated approach, choosing to cycle new bearer tokens every 90 days, which falls short of our recommended limit.

Bearer token invocation quantity

Each environment has a limit on active bearer tokens. When you create a new token, it replaces and invalidates the old ones, with only the newest token being valid in the system.

The following table lists the number of tokens in each environment:

EnvironmentToken
Customer Staging (CS)5
User Acceptance Testing (UAT), and 3
PROD (Production)3

This helps you to manage the token consumption and invocation, particularly within the UAT and PROD environments, where the allocation is more restrictive. Ensure a rotation cycle of bearer tokens to maintain secure access to system resources.

 

The following scenarios demonstrate a flexible token management strategy with varying short-term and long-term validity to meet operational and security requirements, illustrating adaptability in token rotation and renewal.

 

Scenario 1

Create an extended bearer token cycle of 180 days, which involves consuming three bearer tokens over 3 years.

The following are the steps of this scenario:

  1. POST request: Create the first bearer token and set it for 180 days.

  2. POST request: Extend the first bearer token's validity by another 180 days.

  3. DELETE request: Delete the first bearer token after 360 days.

  4. POST request: Invoke creation of the second bearer token and set it for 180 days.

  5. POST request: Extend the second bearer token's validity by another 180 days.

  6. DELETE request: Delete the second bearer token after 360 days.

  7. POST request: Invoke creation of the third bearer token and set for 180 days.

  8. POST request: Extend the third bearer token's validity by another 180 days.

  9. DELETE request: Wipe all the three bearer tokens after 180 days.

  10. Restart the bearer token cycle.

Scenario 2

Create an accelerated bearer token cycle with rotations on every 90 days, which involves consuming three bearer tokens over 1 year.

The following are the steps of this scenario:

  1. POST request: Create the first bearer token and set it for 90 days.
  2. DELETE request: Delete the first bearer token after 90 days.
  3. POST request: Invoke creation of the second bearer token and set it for 90 days.
  4. DELETE request: Delete the second bearer token after 90 days.
  5. POST request: Invoke creation of the third bearer token and set it for 90 days.
  6. DELETE request: Wipe all the three bearer tokens after 90 days.
  7. Restart the bearer token cycle.

Scenario 3

Implement a combined approach that involves accelerated and extended bearer token cycles, with rotations at 90 and 180 days and three bearer tokens over 1.5 years.

The following are the steps of this scenario:

  1. POST request: Create the first bearer token and set it for 90 days.
  2. DELETE request: Delete the first bearer token after 90 days.
  3. POST request: Invoke creation of the second bearer token and set it for 180 days.
  4. POST request: Extend the second bearer token's validity by another 180 days.
  5. DELETE request: Delete the second bearer token after 360 days.
  6. POST request: Invoke creation of the third bearer token and set it for 90 days.
  7. DELETE request: Wipe all the three bearer tokens after 90 days.
  8. Restart the bearer token cycle.

Building API requests

JSON development guidelines: When creating a payload, you must define the Source Systems ID object with the value corresponding to the name of your source system integrated with CDP. This assists CDP to identify the origin of the API calls and ensures that this object is consistently replicated across entities.

If you do not define the source system ID object, the policy automatically assigns a default name,  KFK_0. This can result in confusion when identifying the source system, particularly when multiple sources are assigned the same default name. For example:

{ 
   "events": [
     { 
       "SourceSystemID": "YourSourceSystemName"
     } 
  ], 
 "Customers": [ 
   { 
     "SourceSystemID": "YourSourceSystemName" 
   } 
 ] 
}

TimeStamp payload format

Each payload that contains a system timestamp must be formatted as an epoch value. Epoch time, also known as Unix time, represents time as the number of seconds that have elapsed in Coordinated Universal Time (UTC). If a timestamp is a 13-digit number, it likely represents epoch time in milliseconds. For example, epoch time: 16189320000.

{
  "events": [
    {
      "Timestamp": "16189320000"
    }
  ]
}

This represents the number of seconds that have elapsed since the Unix epoch, which is January 1, 1970, at 00:00:00 UTC.

If you need to test or check an epoch value, see Epoch Converter.

Delete flag

You can remove records from CDP with assistance. You can perform a soft delete, which can be processed into a full deletion based on records' updates that need to be removed from the data model.

Functions

The following are the functions of Delete flag:

  • Soft deleted records are automatically removed from the base tables, also known as Data Warehouse (DW). This function is enabled by a standard attribute present in most entities, except for events. The flag attribute is designed to facilitate the soft deletion of records at the initial stage of the data pipeline.
  • By default, the flag attribute is set to false. If you set it to true, the affected records are marked for soft deletion in the base tables (DW). Following the refresh, the records are removed from the summary tables, known as Business Intelligence (BI), as part of the compaction workflow. This workflow is responsible for the actual deletion of soft deleted records.
  • Soft deleted records are automatically excluded from the tables and views of Persistent Views (PV).
Important

This functionality takes effect as soon as the base tables (DW) receive the record. To ensure that the record is fully deleted, you must wait for the full refresh to see the record removed from the summary tables. 

Considerations when using the Deletion functionality

  • The Event entity does not include a DeleteFlag as it is constant.

  • If the SourceSystemID is not present in the API payload, the system assigns a default value of KFK_0. This could lead to accidental removals of customers if multiple client sources submit data through Tracker API to CDP.

  • When removing a customer from CDP, you must retain their transactional data to preserve historical sales records. Instead of complete deletion, you can label these transactions as Anonymous and Unidentified. Deleting such transactions can affect historical sales figures.  Acquia recommends you to retain them and categorize them as "Unidentified" if they are not linked to a customer.

  • You can only delete records associated with customers having a SourceCustomerNumber or Universally Unique Identifier (UUID) in CDP.

  • This functionality is effective only when combined with the Customer entity for deletion of associated sub-entities.

  • You can delete customer addresses only by including Address or CustomerAddressXref.

  • For custom entities such as PetInfo, deletion requires the provision of specific SourceEntityNumbers. Each entity in CDP has its unique SourceEntityNumber column.