Adaptix OAuth 2.0 Integration: Pop-up Window Approach (JS/SPA)

The pop-up window approach for the Adaptix OAuth 2.0 Authorization Code Flow is used in Single-Page Applications (SPAs) to authenticate a user without forcing the main application window to navigate away. This method securely transports the temporary authorization code from Adaptix back to your backend server, which completes the token exchange and relays the final tokens to the main browser window.

---

1. Parent Window (Your Main App) Logic

The main application window initiates the flow and sets up a listener to receive the final tokens.

1.1. Open the Pop-up

When the user clicks the "Connect Adaptix" button, your JavaScript uses window.open() to initiate the flow, sending the user to the Adaptix Authorization URL (Step 2 of the standard flow).

// Securely generate a unique state for CSRF protection
const state = generateRandomString(); 

// Construct the Adaptix Authorization URL
const adaptixAuthUrl = `https://instance.adaptix.ai/oauth/v2/authorize?` +
    `client_id=YOUR_CLIENT_ID&` +
    `redirect_uri=${encodeURIComponent('https://app.your-domain.com/adaptix/callback')}&` +
    `response_type=code&` +
    `state=${state}`;

// Open the pop-up window
const popupWindow = window.open(
    adaptixAuthUrl,
    'AdaptixAuthPopup',
    'width=600,height=700,scrollbars=yes,resizable=yes'
);

1.2. Listen for the Result

The main window uses the window.postMessage() API to listen for the final tokens securely sent from your callback page.

window.addEventListener('message', (event) => {
    // SECURITY: Always verify the origin of the message
    if (event.origin !== '[https://app.your-domain.com](https://app.your-domain.com)') { // Your app's domain
        return; 
    }

    const { type, payload } = event.data;

    if (type === 'ADAPTIX_AUTH_SUCCESS') {
        const { accessToken, refreshToken } = payload;

        // Final action: Store tokens and update UI
        localStorage.setItem('adaptix_access_token', accessToken);
        // ... update your UI
        console.log('Adaptix connected! Tokens received.');

    } else if (type === 'ADAPTIX_AUTH_ERROR') {
        console.error('Adaptix connection failed:', payload.error);
    }

    // Close the pop-up window after receiving the result
    if (popupWindow && !popupWindow.closed) {
        popupWindow.close();
    }
});

2. Pop-up Window Logic (The Callback Page)

The redirect_uri (e.g., /adaptix/callback) is a simple page on your domain that receives the authorization code from Adaptix.

2.1. Handle the Authorization Code

This page's JavaScript handles the URL parameters, sends the code to your backend server, and relays the resulting tokens back to the parent.

/adaptix/callback Page JavaScript:

// 1. Extract the code and state from the URL query parameters
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const receivedState = urlParams.get('state');

if (code && window.opener) {
    // 2. Send the code (and state) to your secure backend endpoint
    fetch('/api/adaptix/exchange-code', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({ code: code, state: receivedState }),
    })
    .then(response => response.json())
    .then(data => {
        // 3. Backend returns the exchanged tokens
        if (data.accessToken) {
            // 4. Use postMessage to send the final tokens back to the parent window
            window.opener.postMessage(
                {
                    type: 'ADAPTIX_AUTH_SUCCESS',
                    payload: { 
                        accessToken: data.accessToken, 
                        refreshToken: data.refreshToken 
                    }
                },
                window.location.origin // Your app's origin
            );
        } else {
            throw new Error(data.error || 'Token exchange failed on server.');
        }
    })
    .catch(error => {
        // Send error back to parent
        window.opener.postMessage(
            { type: 'ADAPTIX_AUTH_ERROR', payload: { error: error.message } },
            window.location.origin
        );
    })
    .finally(() => {
        // 5. Close the pop-up window
        window.close();
    });

} else if (window.opener) {
    // Handle error case (e.g., user denied access)
    window.opener.postMessage(
        { type: 'ADAPTIX_AUTH_ERROR', payload: { error: 'Authorization failed or cancelled.' } },
        window.location.origin
    );
    window.close();
}

3. Server-Side Endpoint (Backend)

Your backend receives the code and completes the secure exchange using the client_secret (Step 4 of the standard flow).

POST /api/adaptix/exchange-code Logic (Server-Side):

Validate state: Compare the received state against the user's stored session value. Abort if they don't match (CSRF protection).

Exchange Code: Send the secure POST request to the Adaptix Token URL, including your client_secret.

Database: Securely save the access_token and refresh_token associated with your user.

Respond to Pop-up: Return the tokens (or a success indicator) in the JSON response to the callback page.