Session and API Request Management

Overview

The **Session and API Request Management** module is responsible for maintaining an authenticated session with the Qualtrics platform after the user logs in via automated browser interaction. It ensures that subsequent API requests to manage survey collaborations are properly authorized and contain the necessary headers and cookies expected by Qualtrics. This module abstracts away the complexity of session synchronization between the browser-driven login and the HTTP API client, enabling seamless communication with Qualtrics’ backend services.

This functionality is critical because the Qualtrics collaboration API requires authenticated requests accompanied by specific headers, cookies, and tokens that are only available after a successful login sequence executed through Selenium automation. By synchronizing session state and dynamically generating request headers, this module allows programmatic survey collaboration management without manual intervention or repeated logins.

Core Concepts

1. Session State Synchronization

Problem: Selenium automates browser login and obtains session cookies, but API requests made with the requests library require these cookies to be manually synchronized to maintain authentication.
Solution: Extract cookies from the Selenium-controlled browser session and inject them into the requests.Session cookie jar. This enables the HTTP client to reuse the authenticated state established by Selenium for subsequent API calls.

The synchronization occurs immediately after successful login:

cookies = driver.get_cookies()
for cookie in cookies:
    self.session.cookies.set(cookie["name"], cookie["value"])

This ensures that the `requests` session carries all necessary cookies (including authentication tokens) needed by the Qualtrics API.

2. API Header Generation

Qualtrics expects specific HTTP headers on API requests to verify the authenticity and integrity of the client’s calls. These headers include:

x-xsrf-token: A token retrieved from the authenticated cookies to prevent cross-site request forgery.
x-request-id and x-transaction-id: Unique UUIDs generated per request to trace and identify API calls.
Standard headers like accept, content-type, referer, origin, and user-agent.

The module dynamically constructs these headers for each API call via the `_generate_qualtrics_headers` method:

def _generate_qualtrics_headers(self, content_type: str) -> dict:
    return {
        'accept': '*/*',
        'accept-encoding': 'gzip, deflate, br',
        'accept-language': 'en-US,en;q=0.9',
        'content-type': content_type,
        'referer': f'https://{self.subdomain}.qualtrics.com/Q/MyProjectsSection',
        'x-xsrf-token': self.cookies.get('XSRF-TOKEN'),
        'user-agent': self.user_agent,
        'origin': f'https://{self.subdomain}.qualtrics.com',
        'x-request-id': str(uuid.uuid4()),
        'x-transaction-id': str(uuid.uuid4())
    }

This method guarantees that each API request includes fresh and valid headers, maintaining compliance with Qualtrics’ security requirements.

How the Module Works

Login via Selenium: The user credentials are submitted through a headless Chrome browser controlled by Selenium. This process handles complex login flows including two-factor authentication and browser trust prompts.
Session Cookie Extraction: Once logged in, the module extracts all cookies from the Selenium browser session.
Cookie Synchronization: These cookies are transferred into the requests.Session object, enabling authenticated HTTP requests.
Header Preparation: For each API call such as adding collaborators or accepting collaboration codes, the module prepares necessary request headers using current session cookies and generates unique request identifiers.
API Request Execution: The module uses the authenticated session and generated headers to perform POST requests to the Qualtrics collaboration API endpoints.

Interactions with Other Parts of the System

Automated Qualtrics Login Module: The session and API request management depends on the login process executed by Selenium automation. The login module establishes an authenticated browser session, which this module then leverages by extracting cookies.
Survey Collaboration Management Module: The API request management module provides the authenticated session and properly formatted headers that the collaboration management methods use to add collaborators or accept collaboration codes through API calls.
CollaborationClient Class: Both login and collaboration functionalities are encapsulated within this class. The session and API request management are implemented as methods and properties within this class, tying together browser automation and API communication.

Important Concepts & Design Patterns

Session Bridging Pattern: The module bridges the stateful Selenium browser session with the stateless HTTP client session by transferring cookies, enabling a seamless transition from UI-driven authentication to API-driven interactions.
Dynamic Header Generation: Headers required by the API, especially security tokens and unique request IDs, are generated dynamically per request, ensuring freshness and compliance with API expectations.
Encapsulation: All session management details, including cookie handling and header creation, are encapsulated within private methods and properties (_generate_qualtrics_headers, cookies), exposing a clean interface for higher-level collaboration operations.

Key Code Snippets Illustrating Concepts

Cookie Synchronization after Login

cookies = driver.get_cookies()
for cookie in cookies:
    self.session.cookies.set(cookie["name"], cookie["value"])

This snippet shows how the authenticated cookies from Selenium are transferred into the requests session.

Header Generation for API Requests

def _generate_qualtrics_headers(self, content_type: str) -> dict:
    return {
        'accept': '*/*',
        'content-type': content_type,
        'referer': f'https://{self.subdomain}.qualtrics.com/Q/MyProjectsSection',
        'x-xsrf-token': self.cookies.get('XSRF-TOKEN'),
        'user-agent': self.user_agent,
        'origin': f'https://{self.subdomain}.qualtrics.com',
        'x-request-id': str(uuid.uuid4()),
        'x-transaction-id': str(uuid.uuid4())
    }

This method dynamically builds headers, including tokens and unique identifiers, for each API call.

Mermaid Sequence Diagram: Session and API Request Workflow

sequenceDiagram
    participant User
    participant SeleniumBrowser as Selenium Browser
    participant CollaborationClient
    participant QualtricsAPI

    User->>CollaborationClient: Calls login()
    CollaborationClient->>SeleniumBrowser: Automate login with credentials
    SeleniumBrowser-->>CollaborationClient: Login successful + Cookies
    CollaborationClient->>CollaborationClient: Sync cookies to requests.Session
    User->>CollaborationClient: Calls add_collaborator() or enter_collaboration_code()
    CollaborationClient->>CollaborationClient: Generate headers with tokens and UUIDs
    CollaborationClient->>QualtricsAPI: POST request with cookies & headers
    QualtricsAPI-->>CollaborationClient: API response
    CollaborationClient-->>User: Returns API response data

This diagram visualizes the flow from user login through Selenium, session synchronization, and authenticated API request execution.

This documentation page details how session and request management are handled to maintain authenticated communication with Qualtrics APIs after automated login, enabling smooth and secure survey collaboration workflows.