Dynamics Community Forum Thread Details

Delta Link expiration and delta token structure

Hello,

I want to clarify something regarding the delta token structure.

The format is: [Version Number] + [!] + [API Timestamp]

In your documentation you mention that the delta link has an expiration of 7 days and to validate the request, it looks like the API checks only the timestamp part. Meaning, if the timestamp is less than 7 days since the current time, the request will be valid. Otherwise its considered expired.

However, knowing this, what we can do is just build a new delta token, retaining the version number part, and just replacing the timestamp with the current timestamp and the request will be considered valid. I have tried a request with a version number that I got 2 weeks ago, attaching the current timestamp and the API returned me the changed data since that version number.

Can you please give me more details on the timestamp part of the delta token? How its supposed to be used? What's its meant to do on your part ?

Categories:

Dynamics 365 Sales

It sounds like you’ve figured out an important detail about the delta token structure and how the API evaluates it. Let me clarify how this is intended to work and the purpose of the timestamp in the delta token.

1. Delta Token Structure: Version Number and Timestamp

The delta token is generally structured as: [Version Number] + [!] + [API Timestamp].
The Version Number identifies a specific state or checkpoint in the data. It allows the system to know exactly what version of the data the client last retrieved.
The Timestamp acts as a way to control the validity of the delta link, effectively setting an expiration period for the delta link itself.

2. Purpose of the Timestamp

The timestamp is primarily used to ensure that delta tokens don’t stay active indefinitely. By default, delta tokens expire after 7 days, and this timestamp helps enforce that expiration.
When a request is made with a delta token, the API checks the timestamp. If the timestamp is within the allowable window (e.g., less than 7 days old), the API treats the request as valid. If it’s older than 7 days, it considers the delta link expired.
This mechanism prevents clients from relying on outdated tokens indefinitely, ensuring that only relatively recent delta tokens are used for incremental data sync.

3. Using the Timestamp to Extend Delta Token Validity

As you discovered, if you retain the same Version Number and only update the Timestamp part with the current time, the API will accept the token as valid, assuming the timestamp is within the 7-day window.
This works because the delta link’s validity check is based only on the timestamp's recency, not on any inherent association between the timestamp and version number. However, note that this behavior is more of a side effect rather than the intended use of the timestamp.

4. Why This Approach Might Be Risky

Modifying the delta token timestamp to extend its validity isn’t the intended usage pattern and might be risky, especially if the delta token logic or expiration rules are updated in future API versions.
Altering the timestamp without refreshing the token properly could lead to inconsistent data retrieval if the backend state changes in ways that aren’t fully compatible with a stale version number.
To maintain API compatibility and prevent unexpected issues, it’s best to request a fresh delta token if the current one expires.

5. Best Practice for Delta Tokens

The recommended approach is to follow the delta link expiration rules strictly and request a new delta token after the previous one expires (every 7 days).
Using a fresh delta token ensures that you are working with the most accurate checkpoint for data changes and minimizes the risk of data inconsistency or sync errors.

Summary

The timestamp in the delta token is intended as an expiration control mechanism. While it’s possible to manually adjust the timestamp to keep the delta token active, this is not the recommended or supported usage. Modifying the timestamp may work in the current implementation, but it’s not guaranteed to work consistently across all scenarios and may be subject to change in future API updates.

If you need continuous sync over a longer period, consider implementing a mechanism to refresh the delta token on a regular basis, following the 7-day expiration policy. This way, you maintain alignment with the API’s intended usage and avoid potential issues in the future.

Quick Links