Integrating Teleskope Platform with Rewards Vendor

introduction this document outlines the technical design for integrating the teleskope platform with a third party rewards vendor the primary goal of this integration is to enable teleskope users to redeem points, earned and stored within the teleskope platform, for rewards offered by the integrated vendor the integration will facilitate a seamless user experience, secure user identification, and a robust point deduction mechanism with transactional integrity solution overview the integration will leverage a single sign on (sso) mechanism using java web tokens (jwt) for secure user authentication and authorization when transitioning from teleskope to the rewards platform point deduction will be managed through a rest based enterprise application integration (eai) api provided by teleskope, utilizing a two phase commit with rollback to ensure data consistency key components and technologies teleskope platform the system of record for user points and the initiator of the reward redemption process rewards platform the external vendor system that displays and allows redemption of rewards java web tokens (jwt) used for secure, stateless transmission of user identity and point information from teleskope to the rewards platform teleskope eai api a restful api provided by teleskope for programmatic interaction, specifically for point deduction with two phase commit https all communication between platforms will be secured using https integration flows user journey from teleskope to rewards platform user initiates redemption a user logged into the teleskope platform navigates to a "redeem rewards" section and clicks on a "redeem" button teleskope generates jwt upon clicking "redeem," the teleskope backend generates a signed jwt containing the following claims \<font color="#22c55e">firstname \</font> user's first name \<font color="#22c55e">lastname \</font> user's last name \<font color="#22c55e">points \</font> user's current number of points \<font color="#22c55e">email \</font> user's email address \<font color="#22c55e">userid \</font> unique identifier for the user on teleskope \<font color="#22c55e">iat \</font> issued at \<font color="#22c55e">exp \</font> expiration time for jwt validity redirection to rewards platform teleskope redirects the user's browser to a pre configured url on the rewards platform the jwt is passed as a url parameter (e g , \<font color="#22c55e">https //rewards vendor com/redeem?token=\&lt;jwt\&gt;\</font> ) or as part of a post request, depending on the agreed upon method with the rewards vendor for security and url length considerations rewards platform validates jwt upon receiving the request, the rewards platform validates the jwt's signature using a pre shared secret or public key provided by teleskope verifies the \<font color="#22c55e">exp\</font> claim to ensure the token has not expired extracts the user claims (first name, last name, points, email, userid) rewards platform displays user points the rewards platform uses the points claim from the jwt to display the user's available points prominently on their interface, allowing the user to browse and select rewards the user's identity (first name, last name, email) can also be used for personalization point deduction two phase commit with rollback this flow describes how points are deducted from teleskope when a user checks out rewards on the rewards platform phase 1 prepare (commit request) user checks out rewards on the rewards platform, the user selects desired rewards and proceeds to checkout the rewards platform determines the total points required for the selected rewards rewards platform initiates commit request (teleskope eai api) the rewards platform makes a post request to teleskope's eai api \<font color="#22c55e">\</font> endpoint (e g , \<font color="#22c55e">/eai/v1/points?commit\</font> ) this request will include \<font color="#22c55e">user id\</font> the unique id of the user (obtained from the initial jwt) \<font color="#22c55e">points to deduct\</font> the total number of points to be deducted for the chosen rewards \<font color="#22c55e">transaction id\</font> a unique identifier generated by the rewards platform for this specific redemption transaction \<font color="#22c55e">description\</font> a brief description of the reward redemption (e g , "redemption for \[reward name]") teleskope processes commit request upon receiving the \<font color="#22c55e">commit\</font> request, teleskope validates the \<font color="#22c55e">user id\</font> and \<font color="#22c55e">points to deduct\</font> checks if the user has sufficient points available if successful temporarily "holds" or earmarks the \<font color="#22c55e">points to deduct\</font> for the given \<font color="#22c55e">transaction id\</font> , ensuring they cannot be spent elsewhere responds with a \<font color="#22c55e">200 ok \</font> status and a success message, acknowledging the commit request if insufficient points or other error responds with a \<font color="#22c55e">4xx\</font> status code (e g , \<font color="#22c55e">400 bad request\</font> ) and an error message, indicating the failure phase 2 complete (confirm or rollback) scenario a successful redemption (confirm) rewards platform confirms redemption after successfully processing the reward order (e g , confirming inventory, preparing for shipment), the rewards platform makes a post request to teleskope's eai api \<font color="#22c55e">confirm\</font> endpoint (e g , \<font color="#22c55e">/eai/v1/points?confirm\</font> ) this request will include \<font color="#22c55e">user id\</font> the unique id of the user \<font color="#22c55e">transaction id\</font> the same \<font color="#22c55e">transaction id \</font> used in the \<font color="#22c55e">commit\</font> request teleskope processes confirm request upon receiving the \<font color="#22c55e">confirm\</font> request, teleskope permanently deducts the points previously held for the specified \<font color="#22c55e">transaction id\</font> and \<font color="#22c55e">user id\</font> responds with a \<font color="#22c55e">200 ok\</font> status and a success message scenario b failed redemption (rollback) rewards platform rolls back if the reward order cannot be fulfilled for any reason (e g , out of stock, payment failure on rewards platform side), the rewards platform makes a post request to teleskope's eai api \<font color="#22c55e">rollback\</font> endpoint (e g , \<font color="#22c55e">/eai/v1/points?rollback\</font> ) this request will include \<font color="#22c55e">user id\</font> the unique id of the user \<font color="#22c55e">transaction id\</font> the same \<font color="#22c55e">transaction id \</font> used in the \<font color="#22c55e">commit\</font> request teleskope processes rollback request upon receiving the \<font color="#22c55e">rollback\</font> request, teleskope releases the temporarily held points for the specified \<font color="#22c55e">transaction id\</font> and \<font color="#22c55e">user id\</font> , making them available again to the user responds with a \<font color="#22c55e">200 ok \</font> status and a success message api endpoints (teleskope eai api) teleskope will expose the following restful api endpoints \<font color="#22c55e">post /eai/v1/points?commit\</font> description initiates the first phase of the point deduction request body (json) json { "userid" "string", "pointstodeduct" "integer", "transactionid" "string", "description" "string" } response (200 ok json) json { "status" "success", "message" "points committed for transaction" } error responses (4xx json) json { "status" "failed", "message" "error description" } (e g , insufficient points, invalid user) \<font color="#22c55e">post /eai/v1/points?confirm\</font> description confirms the point deduction after successful reward fulfillment request body (json) json { "userid" "string", "transactionid" "string" } response (200 ok json)\ json { "status" "success", "message" "points successfully deducted" } error responses (4xx json) (e g , transaction not found, points already deducted) \<font color="#22c55e">post /eai/v1/points?rollback\</font> description rolls back the point deduction in case of failed reward fulfillment request body (json) json { "userid" "string", "transactionid" "string" } response (200 ok json) json { "status" "success", "message" "points successfully rolled back" } error responses (4xx json) (e g , transaction not found, no points to roll back) security considerations jwt signature jwts will be signed using a strong algorithm (e g , hs256 or rs256) and a secret key or key pair shared only between teleskope and the rewards platform jwt expiration jwts will have a short expiration time to minimize the window of opportunity for replay attacks https everywhere all communication between teleskope and the rewards platform must occur over https to ensure data encryption in transit api authentication/authorization the teleskope eai api should be protected with appropriate authentication and authorization mechanisms (e g , https basic authentication, ip whitelisting) to ensure only the authorized rewards platform can access it input validation both platforms must rigorously validate all incoming data to prevent injection attacks and other vulnerabilities error handling and retries network issues rewards platforms should implement robust retry mechanisms with exponential backoff for transient network failures when making api calls api errors the rewards platform should gracefully handle error responses from the teleskope eai api for instance, if a \<font color="#22c55e">commit \</font> request fails due to insufficient points, the rewards platform should inform the user accordingly