Manage Connections

Learn how to direct users to manage their third party connections

This guide explains how to redirect users to the BlueNexus "Manage Connections" white-label application so they can manage the services (Google, Notion, etc.) connected to their BlueNexus account.

Before following this guide, ensure you've completed Steps 1-4 to create and authenticate BlueNexus accounts for your users.

You can customize the appearance of your white-label web page by uploading your logo and configuring your application details in the developers.md portal.

For a complete React Native implementation example, see the BlueNexus example mobile application.

Authentication Handoff

To redirect your users to the white-label application, you'll initiate an authentication handoff. This process securely transfers the user's authenticated session from your application to the BlueNexus white-label application.

Overview

The redirection to the white-label application works as follows:

1. Your app requests a handoff code from the BlueNexus API

2. Your app redirects the user to the white-label application with the code

3. The user adds or remove connections to their account. (Note: Additional capabilities may be added in the future)

4. The user is then redirected back to your app via the provided redirectUri

5. Your app can refresh its data (for instance to get the updated user's connections)

The Two Essential Steps

Step 1: Request a Handoff Code

Call the handoff initialization endpoint:

POST https://api.bluenexus.ai/api/v1/auth/handoff/init
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "redirectUri": "https://yourapp.com/connections",
  "intent": "connections"
}

Response:

{
  "code": "a1b2c3d4e5f6g7h8i9j0...",
  "expiresAt": "2024-12-31T12:00:30.000Z"
}

Parameters:

• redirectUri: Where to redirect the user after they finish on the white-label page

• intent: Set to "connections" to allow users to manage their connected services (Google, Notion, etc.)

The handoff code expires in 30 seconds. You must redirect the user immediately after receiving the code.

Step 2: Redirect to the White-Label Web Page

Redirect the user to your white-label URL with the code as a query parameter:

https://yourapp.bluenexus.ai?code={HANDOFF_CODE}

Implementation Examples

Web Application

async function redirectToWhiteLabelApp() {
  // Step 1: Request handoff code
  const response = await fetch(
    "https://api.bluenexus.ai/api/v1/auth/handoff/init",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${YOUR_ACCESS_TOKEN}`,
      },
      body: JSON.stringify({
        redirectUri: "https://yourapp.com/connections",
        intent: "connections",
      }),
    }
  );

  const { code } = await response.json();

  // Step 2: Redirect to white-label web page
  window.location.href = `https://yourapp.bluenexus.ai?code=${code}`;
}

Mobile Application (React Native)

import { Linking } from "react-native";

async function redirectToWhiteLabelApp() {
  // Step 1: Request handoff code
  const response = await fetch(
    "https://api.bluenexus.ai/api/v1/auth/handoff/init",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${YOUR_ACCESS_TOKEN}`,
      },
      body: JSON.stringify({
        redirectUri: "yourapp://connections",
        intent: "connections",
      }),
    }
  );

  const { code } = await response.json();

  // Step 2: Open white-label web page in browser
  await Linking.openURL(`https://yourapp.bluenexus.ai?code=${code}`);
}

For mobile apps, use a deep link scheme (e.g., yourapp://connections) as the redirectUri. For web apps, use a full URL (e.g., https://yourapp.com/connections).

Handling User Return

After users complete their actions on the white-label page, they'll be redirected back to your redirectUri. You should refresh your data at this point.

Web Application

// On your connections page
useEffect(() => {
  // Refresh connections data when page loads
  refetchConnections();
}, []);

Mobile Application

Configure your app to handle deep links:

Expo (app.json):

{
  "expo": {
    "scheme": "yourapp"
  }
}

Listen for deep link events:

import { useEffect } from "react";
import { Linking } from "react-native";

useEffect(() => {
  const subscription = Linking.addEventListener("url", (event) => {
    // User returned from white-label page - refresh data
    refetchConnections();
  });

  return () => subscription.remove();
}, []);

Security Considerations

The authentication handoff uses several security measures:

• Short-lived codes: Handoff codes expire in 30 seconds

• IP fingerprinting: We currently use IP fingerprinting as an extra layer of security, matching the initialization with the finalization. In the case of the initialization is executed from your server and therefore a different IP than where the user will open the white-label web app, please contact us.

• One-time use: Each code can only be used once

• Scoped access: The web session is limited to the requested intent (e.g., the connections intent grant connection-related scopes only)