User Pairing Guide
This guide provides a step-by-step overview of the unique browser-based pairing process, enabling you to successfully integrate and manage user pairings. Understanding this process is crucial for a seamless integration, ensuring that your users can be accurately paired and managed within our system.
Overview
The pairing process is a pivotal step in linking your users to our system. It involves a live, browser-based workflow where the user starts from a pairing link, proceeds through our login or registration process, and finally gets redirected to your specified Redirect URL with a unique Client-Specific User ID (CSU-ID) as a query parameter. This CSU-ID is essential for identifying the user on our platform and must be mapped to their user ID in your system.
Prerequisites
Before initiating the pairing process, ensure you have the following:
- Partner ID (
partnerId): A unique identifier for your organization provided by our team. - Redirect URL: The URL provided by you, where users will be redirected after the pairing process, carrying the CSU-ID.
- Pairing endpoint: A unique URL that initiates the pairing process for your users, pairing endpoint
/partners/{partnerId}/activation. Note that this endpoint does not require any authentication, it's - API Base URL: The base URL for our API, which will be used for making subsequent API calls
https://dealer.prod.ps.axelspringer.de/api/v1/.
https://dealer.prod.ps.axelspringer.de/api/v1/partners/{partnerId}/activationPairing Process Flow
Initiating Pairing: Start the process by providing the user with a pairing link. This link directs the user to our login or registration page, initiating their pairing journey.
User Authentication: Upon clicking the pairing link, the user is taken to our authentication system. Here, they will either log in to their existing account or register for a new one, depending on whether they are already registered with our system.
Redirection with CSU-ID: After successful authentication, we generate a unique CSU-ID for the user. The user is then redirected to your specified Redirect URL, with the CSU-ID appended as a query parameter (e.g.,
https://your-redirect-url.com/?csuId=XYZ123). This step concludes the pairing process.Mapping CSU-ID: It is imperative that you capture and store this CSU-ID on your end. This identifier will be required in all subsequent API calls related to the user, allowing you to manage their subscriptions and purchases through our API.
Partner-Token
To further facilitate the mapping of the CSU-ID to your user, you can use the partner-token query parameter in the pairing link. This parameter will be passed back to your Redirect URL, allowing you to identify the user initiating the pairing process and map the CSU-ID back to them.
DANGER
Be aware that using the partner-token parameter introduces a potential security risk. An attacker could exploit this by (re-)assigning an arbitrary CSU-ID to a user by simply repeating the request with the same partner token but a different CSU-ID, leading to a man-in-the-middle attack. It's crucial to implement additional security measures to mitigate this risk.
Best Practices
- Secure Storage: Ensure the CSU-ID is stored securely within your system to maintain user privacy and data integrity.
- Error Handling: Implement robust error handling for scenarios where the redirection might fail or the CSU-ID is not correctly appended. Providing clear instructions to the user in such cases enhances the user experience.
Next Steps
After successfully completing the pairing process and mapping the CSU-ID to your user IDs, you are ready to proceed with making authenticated API calls for purchasing products, and handling cancellations. Refer to our Authentication Guide, Purchase Guide, and Cancellation Guide for further details on these processes.
You can check the Mermaid diagram here for a more detailed view of the flow for the user pairing process.
Support
For additional guidance or support, please refer to our Developer Guides or contact our Support Team.