White Label Integration

This guide explains how to create and manage BlueNexus accounts programmatically on behalf of your existing users — a key step for enabling white-label integrations.

If you already have users authenticated in your own system (via email/password, SSO, or a social provider), you can use the BlueNexus API to create and manage corresponding accounts seamlessly, without requiring your users to manually sign up with BlueNexus.

Prerequisites

Before you begin, ensure that you've completed the following steps:

1. Created a BlueNexus account.

2. Registered an application and obtained your Client ID and Client Secret.

3. Have an existing application with a user management system (your own app's users).

Creating BlueNexus Accounts

At a high level, the flow for provisioning BlueNexus accounts programmatically works as follows:

1. Generate a cryptographic wallet that represents your user within BlueNexus.

2. Store the wallet securely using your platform's secure storage mechanism.

3. Create a BlueNexus account for your user by signing an authorization message.

4. Sign a Sign-In With Ethereum (SIWE) message to prove key ownership and authenticate with BlueNexus.

5. Send the signed authentication request to BlueNexus to obtain an access token and refresh token.

6. Store the access and refresh tokens securely in your secure storage.

7. Use the access token to make API requests on behalf of your user.

8. Handle expired access tokens by refreshing them on behalf of your user.

9. Optionally, direct users to manage their connections via a BlueNexus white-label page.

Step 1: Generate a Cryptographic Wallet for Your User

Each of your users needs a unique cryptographic wallet that identifies them within BlueNexus. This wallet allows you to sign authentication requests and securely act on their behalf.

Wallet Libraries: To generate a proper EVM-compatible wallet and sign SIWE messages, we recommend using established crypto libraries that follow blockchain best practices:

• ethers.js - Popular, well-maintained, comprehensive Ethereum library

• viem - Modern, type-safe alternative with better TypeScript support

• web3.js - Widely used, especially in legacy projects

These libraries handle wallet generation, mnemonic management, and message signing securely according to blockchain standards (BIP-39, BIP-44, EIP-191, etc.).

Example using ethers.js:

import { Wallet, Mnemonic } from "ethers";

async function getOrCreateWallet(userId: string) {
  // Check if user already has a wallet mnemonic stored
  const existingMnemonic = await getMnemonicFromDB(userId); // Your own implementation to retrieve a stored mnemonic for your user based on its id
  if (existingMnemonic) {
    return Wallet.fromPhrase(existingMnemonic);
  }

  // Generate new wallet with 16 bytes of secure random entropy
  const entropy = getSecureRandomBytes(16); // Use your platform's crypto API
  const mnemonic = Mnemonic.fromEntropy(entropy);
  const wallet = Wallet.fromPhrase(mnemonic.phrase);

  // Store the mnemonic securely
  await saveMnemonicToDB(userId, mnemonic.phrase); // Your own implementation to securely store the user's mnemonic

  return wallet;
}

const wallet = await getOrCreateWallet(userId);
const userAddress = wallet.address.toLowerCase();

Secure Storage: Use your platform's secure storage mechanism:

• Web/Server: Encrypted database storage with proper key management

• iOS: Keychain Services

• Android: Keystore System

• React Native/Expo: expo-secure-store or react-native-keychain

• Flutter: flutter_secure_storage

Secure Random Bytes: Use your platform's cryptographically secure random number generator:

• Web: crypto.getRandomValues()

• Node.js: crypto.randomBytes()

• React Native/Expo: expo-crypto.getRandomBytes() or react-native-get-random-values

• iOS: SecRandomCopyBytes()

• Android: SecureRandom

Security Note: The wallet mnemonic is sensitive data that grants access to the user's BlueNexus account. Always encrypt mnemonics before storing them in your database and implement proper access controls to protect user data.

Step 2: Create a BlueNexus Account

Before authenticating, you must create a BlueNexus account for your user. This is done by signing an authorization message and calling the account creation endpoint.

Idempotent Endpoint: This endpoint is idempotent — if an account already exists for the given address, it will return the existing account without creating a duplicate. However, we recommend tracking which users have accounts to avoid unnecessary API calls.

Sign the authorization message:

const AUTHORIZATION_MESSAGE = "I authorize BlueNexus to use my cryptographic address";

// Sign the authorization message with the user's wallet
const signature = await wallet.signMessage(AUTHORIZATION_MESSAGE);

Public Client Account Creation

For public clients without a client secret:

async function createBlueNexusAccount(wallet, clientId, profile?) {
  const signature = await wallet.signMessage(
    "I authorize BlueNexus to use my cryptographic address"
  );

  const response = await fetch("https://api.bluenexus.ai/api/v1/accounts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      address: wallet.address.toLowerCase(),
      signature: signature,
      client_id: clientId,
      // Optional: Include profile data (name, email, avatar)
      profile: profile,
    }),
  });

  if (!response.ok) {
    throw new Error(`Account creation failed: ${response.statusText}`);
  }

  return response.json();
}

// Usage with optional profile
const account = await createBlueNexusAccount(wallet, clientId, {
  name: "John Doe",
  email: "[email protected]",
  avatar: "https://example.com/avatar.jpg",
});

Confidential Client Account Creation

For confidential clients with a client secret, use Basic Authentication:

async function createBlueNexusAccount(wallet, clientId, clientSecret, profile?) {
  const signature = await wallet.signMessage(
    "I authorize BlueNexus to use my cryptographic address"
  );

  const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");

  const response = await fetch("https://api.bluenexus.ai/api/v1/accounts", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Basic ${credentials}`,
    },
    body: JSON.stringify({
      address: wallet.address.toLowerCase(),
      signature: signature,
      profile: profile,
    }),
  });

  if (!response.ok) {
    throw new Error(`Account creation failed: ${response.statusText}`);
  }

  return response.json();
}

Account Creation Response:

{
  "id": "507f1f77bcf86cd799439011",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "roles": ["user"],
  "status": "active",
  "profile": {
    "name": "John Doe",
    "email": "[email protected]",
    "avatar": "https://example.com/avatar.jpg"
  },
  "createdAt": "2025-11-15T10:30:00.000Z",
  "updatedAt": "2025-11-15T10:30:00.000Z"
}

Profile Fields: All profile fields are optional:

• name: Display name (1-255 characters)

• email: Valid email address

• avatar: HTTPS URL or base64 data URI (max 2MB)

Tracking Accounts: Track in your database which user/address already has a BlueNexus account. This allows you to skip the account creation step for returning users.

Step 3: Authenticate Using SIWE (Sign-In With Ethereum)

BlueNexus uses SIWE (Sign-In With Ethereum) for authentication. This standard proves the ownership of the address/wallet by signing a message. As you are the custodian of the user's wallet (mnemonic or private key - see above), you can sign this message and authenticate on their behalf.

Client Credentials Requirements:

• Public clients (no client secret): MUST provide client_id in the request body

• Confidential clients (with client secret): MUST provide both client_id and client_secret using either:

  • Basic Authentication header (recommended)

  • Request body parameters

See Application Typesfor more information on public v confidential clients.

Public Client Authentication

For public clients without a client secret:

import { SiweMessage, generateNonce } from "siwe";

async function authenticateWithBlueNexus(wallet, clientId) {
  // Create a SIWE message
  const message = new SiweMessage({
    domain: "your-app.com", // Same as the `domain` registered with your BlueNexus client
    address: wallet.address,
    uri: "https://your-app.com", // Your application's URI
    version: "1",
    chainId: 1, // Ethereum mainnet
    nonce: generateNonce(),
    issuedAt: new Date().toISOString(),
  });

  // Format and sign the message
  const messageString = message.prepareMessage();
  const signature = await wallet.signMessage(messageString);

  // Send authentication request with client_id in body
  const response = await fetch("https://api.bluenexus.ai/api/v1/auth/authenticate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      payload: message,
      signature: signature,
      client_id: clientId,
    }),
  });

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.statusText}`);
  }

  const data = await response.json();
  return data; // { access_token, refresh_token, expires_in }
}

Confidential Client Authentication

For confidential clients with a client secret, choose one of the following methods:

Option 1: Basic Authentication (Recommended)

// Encode credentials as Base64
const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");

const response = await fetch("https://api.bluenexus.ai/api/v1/auth/authenticate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Basic ${credentials}`,
  },
  body: JSON.stringify({
    payload: message,
    signature: signature,
  }),
});

Option 2: Body Parameters

const response = await fetch("https://api.bluenexus.ai/api/v1/auth/authenticate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    payload: message,
    signature: signature,
    client_id: clientId,
    client_secret: clientSecret,
  }),
});

What is SIWE? Sign-In With Ethereum (SIWE) is an open standard for decentralized identity and authentication. It allows users to prove ownership of their Ethereum address by signing a standardized message. Learn more at login.xyz.

Step 4: Store Access and Refresh Tokens

Once the authentication request succeeds, you'll receive a response with tokens:

Authentication Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Field	Description
access_token	JWT token used for API calls (short-lived)
refresh_token	JWT token used to obtain new access tokens (long-lived)
expires_in	Number of seconds until the access token expires

Store these tokens securely:

// Example: Store tokens for the user
await saveTokens(userId, {
  accessToken: data.access_token,
  refreshToken: data.refresh_token,
  expiresIn: new Date(Date.now() + data.expires_in * 1000), // Convert seconds to milliseconds timestamp
});

Step 5: Make API Requests on Behalf of the User

Once you have a valid access token, you can make authenticated requests to BlueNexus APIs representing that user.

// Retrieve the access token
const tokens = await getTokens(userId);
const accessToken = tokens.accessToken;

// Make an authenticated API request
const response = await fetch("https://api.bluenexus.ai/api/v1/accounts/me", {
  headers: {
    "Authorization": `Bearer ${accessToken}`,
  },
});

if (!response.ok) {
  throw new Error(`API request failed: ${response.statusText}`);
}

const account = await response.json();

Step 6: Handle expired access tokens

See Expired tokens

Manage user Connections

BlueNexus provides a white-label "Manage user Connections" application that allows you to redirect a user to easily connect and disconnect third party applications (ie: Google, Notion, Wearables data etc.) to their BlueNexus account, and hence your application.

This application can be customized to match your company branding for a seamless experience.

Learn how to integrate with the Manage Connectionsapplication.

What's Next?

Now you have established a BlueNexus account on behalf of your users, you can use the BlueNexus infrastructure within your application:

• Learn how to connect user data to your large language model

• Learn how to access third party APIs connected by your users

• Learn how to read / write encrypted user data

• BlueNexus API Reference