Skip to main content

Vectorize-Managed OAuth

Vectorize-Managed OAuth connectors allow you to integrate multiple users' cloud storage and productivity platform accounts using Vectorize's pre-configured OAuth applications. This approach eliminates the need to set up and maintain your own OAuth credentials, letting you focus on building your application.

Why Choose Vectorize-Managed OAuth​

  • Quick Setup: No OAuth app configuration required
  • Vectorize maintains the underlying OAuth apps for each platform: Vectorize handles OAuth app maintenance and updates
  • Simplified Development: Focus on your application logic, not OAuth complexity
  • Reliable Authentication: Benefit from Vectorize's tested and maintained OAuth flows
note

Available on Starter plan and above

Supported Platforms​

Vectorize 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.

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 Vectorize connectors
VECTORIZE_API_KEY=your_vectorize_api_token
VECTORIZE_ORGANIZATION_ID=your_organization_id

3. Create Your First Connector​

Follow the Creating Connectors Guide for detailed implementation examples.

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

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

// Create a connector for your chosen platform
const connectorId = await createVectorizeConnector(
  vectorizeConfig,
  "Team Storage Connector"
);

console.log('Connector created:', connectorId);

User Authentication Flow​

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

1. Generate One-Time Token​

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

const tokenResponse = await getOneTimeConnectorToken(
  vectorizeConfig,
  userId, // Your application's user ID
  connectorId
);

2. Redirect to Vectorize Authentication​

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

// Redirect user to Vectorize's platform authentication
await PlatformOAuth.redirectToVectorizeConnect(
  tokenResponse.token,
  vectorizeConfig.organizationId
);

User Management​

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

Adding Users​

Users are added through the Vectorize authentication flow. Once a user completes authentication, they're automatically added to your connector.

Managing Existing Users​

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

// Update user file selection
await manageUser(
  vectorizeConfig,
  connectorId,
  userId,
  'edit',
  { selectedFiles: newFileSelection }
);

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

File Selection​

Editing User File Selection​

To allow users to modify their file selection:

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

// Generate token for editing
const tokenResponse = await getOneTimeConnectorToken(
  vectorizeConfig,
  userId,
  connectorId
);

// Redirect to Vectorize edit flow
await PlatformOAuth.redirectToVectorizeEdit(
  tokenResponse.token,
  vectorizeConfig.organizationId
);

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

Complete Implementation Example​

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

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

  async createConnector(name: string, platformType: string) {
    return await createVectorizeConnector(this.config, name, platformType);
  }

  async addUser(connectorId: string, userId: string) {
    // Generate one-time token
    const tokenResponse = await getOneTimeConnectorToken(
      this.config,
      userId,
      connectorId
    );

    // Redirect to Vectorize authentication flow
    await PlatformOAuth.redirectToVectorizeConnect(
      tokenResponse.token,
      this.config.organizationId
    );
  }

  async removeUser(connectorId: string, userId: string) {
    await manageUser(
      this.config,
      connectorId,
      userId,
      'remove'
    );
  }
}

// Usage
const manager = new VectorizeConnectorManager();
const connectorId = await manager.createConnector("Team Storage", "PLATFORM_OAUTH_MULTI");
await manager.addUser(connectorId, "user123");

Error Handling​

try {
  const connectorId = await createVectorizeConnector(
    vectorizeConfig,
    "My Connector",
    "PLATFORM_OAUTH_MULTI"
  );
} 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 {
    console.error('Connector creation failed:', error.message);
  }
}

Troubleshooting​

Common Issues​

Connector Creation Fails

  • Verify your VECTORIZE_API_KEY is valid and has the correct permissions
  • Ensure your organization has the required plan (Starter+ for Vectorize connectors)
  • Check that your VECTORIZE_ORGANIZATION_ID ID is correct

User Authentication Issues

  • Confirm the one-time token hasn't expired (tokens have a short TTL)
  • Verify the user is being redirected to the correct Vectorize authentication URL
  • Check that the user has the necessary permissions for their cloud storage account

File Access Problems

  • Ensure users have granted the required permissions during authentication
  • Verify that the files are accessible and haven't been moved or deleted
  • Check for any changes in the user's cloud storage permissions

Testing​

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

Use the test-vectorize-connect-sdk repository for testing:

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

# Set up environment variables
echo "VECTORIZE_API_KEY=your_token" >> .env.local
echo "VECTORIZE_ORGANIZATION_ID=your_org_id" >> .env.local

npm run dev

Next Steps​

  1. Create your first connector using the examples above
  2. Implement user authentication flows in your application
  3. Test the complete user journey from authentication to file selection
  4. Set up proper error handling for production use
  5. Monitor connector usage through the Vectorize platform

For more advanced use cases or custom branding requirements, consider White-Labeled OAuth.

Step-by-Step Implementation Guides​

Was this page helpful?