White-Labeled OAuth

White-Labeled OAuth connectors allow you to integrate multiple users' cloud storage and productivity platform accounts using your own OAuth applications. This approach provides complete control over the authentication experience and branding while leveraging Vectorize's platform for user management and file processing.

Why Choose White-Labeled OAuth Connectors

• Custom Branding: Use your own OAuth applications and maintain brand consistency
• Full Control: Complete control over the authentication flow and user experience
• Security Compliance: Meet specific organizational security and compliance requirements
• Production Ready: Ideal for production applications with custom requirements

note

Available on Pro plan and above

Supported Platforms

White Label connectors support various cloud storage and productivity platforms. The specific platforms available may vary over time as new integrations are added or existing ones are updated.

Prerequisites

Before implementing White Label connectors, you need to set up OAuth applications for each platform you want to support. Each platform has its own developer console and OAuth configuration requirements.

General OAuth Setup Steps

1. Create a developer account with your chosen platform's developer portal
2. Create an OAuth application in the platform's developer console
3. Configure OAuth settings including redirect URIs and required scopes
4. Obtain OAuth credentials (client ID, client secret, API keys as needed)
5. Set up proper permissions and access levels for your application

Platform-Specific Requirements

Each platform has specific OAuth requirements, scopes, and configuration steps. Refer to the platform's developer documentation for detailed setup instructions including:

• Required OAuth scopes and permissions
• Redirect URI configuration
• API access setup
• Production approval processes (if applicable)

Quick Start

1. Install the SDK

npm install @vectorize-io/vectorize-connect

2. Set Environment Variables

See the detailed Environment Setup Guide for complete configuration instructions.

# Required for all White Label connectors
VECTORIZE_API_KEY=your_vectorize_api_token
VECTORIZE_ORGANIZATION_ID=your_organization_id

# Platform-specific OAuth credentials (replace with your platform's requirements)
PLATFORM_OAUTH_CLIENT_ID=your_oauth_client_id
PLATFORM_OAUTH_CLIENT_SECRET=your_oauth_client_secret
PLATFORM_API_KEY=your_api_key_if_required

3. Create Your First Connector

Follow the Creating Connectors Guide for detailed implementation examples.

import { createWhiteLabelConnector } from '@vectorize-io/vectorize-connect';

const vectorizeConfig = {
  authorization: process.env.VECTORIZE_API_KEY!,
  organizationId: process.env.VECTORIZE_ORGANIZATION_ID!,
};

// Create a White Label connector for your chosen platform
const connectorId = await createWhiteLabelConnector(
  vectorizeConfig,
  "Custom Platform Connector",
  "YOUR_PLATFORM_OAUTH_MULTI", // Use your platform's connector type
  {
    clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
    clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
    apiKey: process.env.PLATFORM_API_KEY // If required by platform
  }
);

console.log('White Label connector created:', connectorId);

User Authentication Flow

For complete authentication implementation with API routes and frontend components, see the Authentication Guide.

1. Set Up OAuth Configuration

import { PlatformOAuth } from '@vectorize-io/vectorize-connect';

const oauthConfig = {
  clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
  clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
  apiKey: process.env.PLATFORM_API_KEY!, // If required by platform
  redirectUri: `${window.location.origin}/api/platform-callback`,
  onSuccess: (response) => {
    console.log('Authentication successful:', response);
    // Handle successful authentication
  },
  onError: (error) => {
    console.error('Authentication failed:', error);
    // Handle authentication error
  }
};

2. Start OAuth Flow

// Start platform OAuth flow
const popup = PlatformOAuth.startOAuth(oauthConfig);

3. Handle OAuth Callback

Create API routes to handle OAuth callbacks:

// pages/api/platform-callback.ts (Next.js example)
import { PlatformOAuth, exchangeCodeForTokens } from '@vectorize-io/vectorize-connect';

export default async function handler(req, res) {
  const { code, error } = req.query;
  
  if (error) {
    return res.status(400).json({ error });
  }

  try {
    // Exchange code for tokens
    const tokens = await exchangeCodeForTokens(
      code,
      process.env.PLATFORM_OAUTH_CLIENT_ID!,
      process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
      `${process.env.NEXTAUTH_URL}/api/platform-callback`
    );

    // Create callback response with file picker
    const response = await PlatformOAuth.createCallbackResponse(
      code,
      {
        clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
        clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
        apiKey: process.env.PLATFORM_API_KEY!,
        redirectUri: `${process.env.NEXTAUTH_URL}/api/platform-callback`,
        onSuccess: (selection) => {
          // Handle file selection
          console.log('Files selected:', selection);
        },
        onError: (error) => {
          console.error('File selection error:', error);
        }
      }
    );

    return response;
  } catch (error) {
    console.error('OAuth callback error:', error);
    return res.status(500).json({ error: 'Authentication failed' });
  }
}

User Management

For detailed user management implementation including API routes and frontend examples, see the User Management Guide.

Adding Users with File Selection

import { 
  PlatformOAuth, 
  PlatformSelection,
  manageUser 
} from '@vectorize-io/vectorize-connect';

class WhiteLabelConnectorManager {
  private config = {
    authorization: process.env.VECTORIZE_API_KEY!,
    organizationId: process.env.VECTORIZE_ORGANIZATION_ID!,
  };

  async addPlatformUser(connectorId: string, userId: string) {
    const oauthConfig = {
      clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
      clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
      apiKey: process.env.PLATFORM_API_KEY!,
      redirectUri: `${window.location.origin}/api/platform-callback`,
      onSuccess: async (authResponse) => {
        // Start file selection after authentication
        const selectionPopup = await PlatformSelection.startFileSelection(
          oauthConfig,
          authResponse.refresh_token,
          {} // No pre-selected files for new user
        );
      },
      onError: (error) => {
        console.error('Authentication failed:', error);
      }
    };

    // Start OAuth flow
    const popup = PlatformOAuth.startOAuth(oauthConfig);
  }
}

Managing Existing Users

import { manageUser } from '@vectorize-io/vectorize-connect';

// Update user file selection
await manageUser(
  vectorizeConfig,
  connectorId,
  userId,
  'edit',
  { 
    selectedFiles: newFileSelection,
    refreshToken: userRefreshToken // Include refresh token for White Label
  }
);

// Remove a user
await manageUser(
  vectorizeConfig,
  connectorId,
  userId,
  'remove'
);

Platform-Specific User Management

For platform-specific operations, you can use specialized user management functions that handle platform-specific token management and file operations. These functions provide optimized workflows for each supported platform.

File Selection

For more file selection patterns and examples, see the Frontend Implementation Guide.

Platform File Selection

import { PlatformSelection } from '@vectorize-io/vectorize-connect';

const popup = await PlatformSelection.startFileSelection(
  {
    clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
    clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
    apiKey: process.env.PLATFORM_API_KEY!,
    redirectUri: `${window.location.origin}/api/platform-callback`,
    onSuccess: (selection) => {
      console.log('Files selected:', selection);
      // Update user's file selection in the connector
    },
    onError: (error) => {
      console.error('File selection failed:', error);
    }
  },
  userRefreshToken,
  existingSelection // Pre-populate with current selection
);

Token Management

Refreshing Access Tokens

import { refreshPlatformToken } from '@vectorize-io/vectorize-connect';

// Refresh platform token
const newTokens = await refreshPlatformToken(
  storedRefreshToken,
  process.env.PLATFORM_OAUTH_CLIENT_ID!,
  process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
  'YOUR_PLATFORM_TYPE' // Use your platform's type identifier
);

Token Storage Best Practices

For White Label connectors, you're responsible for securely storing and managing OAuth tokens:

// Example token storage interface
interface TokenStorage {
  storeTokens(userId: string, platform: string, tokens: OAuthTokens): Promise<void>;
  getTokens(userId: string, platform: string): Promise<OAuthTokens | null>;
  refreshTokens(userId: string, platform: string): Promise<OAuthTokens>;
  revokeTokens(userId: string, platform: string): Promise<void>;
}

class SecureTokenStorage implements TokenStorage {
  async storeTokens(userId: string, platform: string, tokens: OAuthTokens) {
    // Encrypt and store tokens in your database
    // Never store tokens in plain text
  }

  async refreshTokens(userId: string, platform: string) {
    const tokens = await this.getTokens(userId, platform);
    if (!tokens?.refresh_token) {
      throw new Error('No refresh token available');
    }

    return await refreshPlatformToken(
      tokens.refresh_token,
      process.env.PLATFORM_OAUTH_CLIENT_ID!,
      process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
      platform
    );
  }
}

Complete Implementation Example

import { 
  createWhiteLabelConnector,
  PlatformOAuth,
  PlatformSelection,
  manageUser,
  refreshPlatformToken
} from '@vectorize-io/vectorize-connect';

class WhiteLabelPlatformManager {
  private config = {
    authorization: process.env.VECTORIZE_API_KEY!,
    organizationId: process.env.VECTORIZE_ORGANIZATION_ID!,
  };

  private oauthConfig = {
    clientId: process.env.PLATFORM_OAUTH_CLIENT_ID!,
    clientSecret: process.env.PLATFORM_OAUTH_CLIENT_SECRET!,
    apiKey: process.env.PLATFORM_API_KEY!,
    redirectUri: `${process.env.BASE_URL}/api/platform-callback`,
  };

  async createConnector(name: string, platformType: string) {
    return await createWhiteLabelConnector(
      this.config,
      name,
      platformType,
      {
        clientId: this.oauthConfig.clientId,
        clientSecret: this.oauthConfig.clientSecret,
        apiKey: this.oauthConfig.apiKey
      }
    );
  }

  async authenticateUser(connectorId: string, userId: string) {
    const popup = PlatformOAuth.startOAuth({
      ...this.oauthConfig,
      onSuccess: async (authResponse) => {
        // Store tokens securely
        await this.storeUserTokens(userId, authResponse);
        
        // Start file selection
        await this.selectFiles(userId, authResponse.refresh_token);
      },
      onError: (error) => {
        console.error('Authentication failed:', error);
      }
    });

    return popup;
  }

  async selectFiles(userId: string, refreshToken: string, existingSelection = {}) {
    const popup = await PlatformSelection.startFileSelection(
      {
        ...this.oauthConfig,
        onSuccess: async (selection) => {
          // Update user's file selection in the connector
          await this.updateUserSelection(userId, selection);
        },
        onError: (error) => {
          console.error('File selection failed:', error);
        }
      },
      refreshToken,
      existingSelection
    );

    return popup;
  }

  async updateUserSelection(userId: string, selection: any) {
    const tokens = await this.getUserTokens(userId);
    
    await manageUser(
      this.config,
      this.connectorId,
      userId,
      'edit',
      { 
        selectedFiles: selection,
        refreshToken: tokens.refresh_token
      }
    );
  }

  async refreshUserTokens(userId: string, platformType: string) {
    const tokens = await this.getUserTokens(userId);
    
    const newTokens = await refreshPlatformToken(
      tokens.refresh_token,
      this.oauthConfig.clientId,
      this.oauthConfig.clientSecret,
      platformType
    );

    await this.storeUserTokens(userId, newTokens);
    return newTokens;
  }

  private async storeUserTokens(userId: string, tokens: any) {
    // Implement secure token storage
  }

  private async getUserTokens(userId: string) {
    // Implement secure token retrieval
  }
}

Error Handling

try {
  const connectorId = await createWhiteLabelConnector(
    vectorizeConfig,
    "My Connector",
    "YOUR_PLATFORM_OAUTH_MULTI",
    {
      clientId: clientId,
      clientSecret: clientSecret
    }
  );
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid Vectorize API token');
  } else if (error.response?.status === 403) {
    console.error('Insufficient permissions or plan limitations');
  } else if (error.response?.status === 400) {
    console.error('Invalid OAuth credentials provided');
  } else {
    console.error('Connector creation failed:', error.message);
  }
}

Troubleshooting

Common Issues

OAuth Configuration Problems

• Verify your OAuth client credentials are correct
• Ensure redirect URIs match exactly (including protocol and port)
• Check that your OAuth app has the required scopes and permissions
• Confirm your OAuth consent screen is properly configured

Token Management Issues

• Implement proper token refresh logic before tokens expire
• Store tokens securely and never expose them in client-side code
• Handle token revocation gracefully
• Monitor for changes in OAuth app permissions

File Access Problems

• Verify users have granted the necessary permissions during authentication
• Check that your OAuth app has the required scopes for file access
• Ensure files haven't been moved, deleted, or had permissions changed
• Monitor for API rate limiting and implement appropriate backoff strategies

Platform-Specific Troubleshooting

Platform API Issues

• Verify the platform API is enabled in your developer console/project
• Check that your OAuth consent screen is published (not in testing mode for production)
• Ensure your redirect URIs are added to the OAuth client configuration
• Monitor platform API quotas and usage limits
• Confirm your app has the required permissions for file access
• Verify that your app is approved for production use if required by the platform
• Check that OAuth redirect URIs are correctly configured
• Monitor platform API rate limits and implement appropriate backoff strategies

Testing

For comprehensive testing strategies and examples, see the Testing Guide.

Use the test-vectorize-connect-sdk repository for testing White Label functionality:

git clone https://github.com/vectorize-io/test-vectorize-connect-sdk.git
cd test-vectorize-connect-sdk
npm install

# Set up all required environment variables
echo "VECTORIZE_API_KEY=your_token" >> .env.local
echo "VECTORIZE_ORGANIZATION_ID=your_org_id" >> .env.local
echo "PLATFORM_OAUTH_CLIENT_ID=your_client_id" >> .env.local
echo "PLATFORM_OAUTH_CLIENT_SECRET=your_client_secret" >> .env.local
echo "PLATFORM_API_KEY=your_api_key" >> .env.local

npm run dev

Security Best Practices

1. Token Security

   • Encrypt tokens at rest
   • Use secure token storage (database, not local storage)
   • Implement token rotation
   • Never expose tokens in client-side code

2. OAuth Security

   • Use HTTPS for all OAuth flows
   • Validate redirect URIs strictly
   • Implement CSRF protection
   • Monitor for suspicious authentication patterns

3. API Security

   • Implement rate limiting
   • Use secure API key storage
   • Monitor API usage patterns
   • Implement proper error handling without exposing sensitive information

Next Steps

1. Set up OAuth applications for your chosen platforms
2. Configure environment variables with your OAuth credentials
3. Implement authentication flows with proper error handling
4. Set up secure token storage for production use
5. Test the complete user journey from authentication to file selection
6. Deploy with proper security measures and monitoring

Related Documentation

• Vectorize Connect SDK API Reference
• Test Examples Repository

Step-by-Step Implementation Guides

• Environment Setup
• Creating Connectors
• Authentication
• User Management
• Frontend Implementation
• Testing