​
Overview

Bluvo’s OAuth2 integration enables your users to securely connect their exchange accounts through standardized OAuth2 flows, eliminating the need to handle sensitive API credentials directly. Instead of managing raw access tokens, Bluvo returns encrypted wallet IDs that internally resolve to the proper authentication credentials using our enterprise-grade encryption system.

​
Motivation

Traditional crypto exchange integrations require users to manually create API keys and share them with third-party applications. This approach has several critical limitations:
  • Security risks from exposing sensitive API credentials to applications
  • Poor user experience requiring technical knowledge to create API keys
  • Limited scope control with API keys often having broader permissions than needed
  • No standardization across different exchanges with varying API key formats
  • Credential management burden for both users and developers
OAuth2 provides a standardized, secure alternative that:
  • Allows users to authenticate directly with their exchange
  • Provides granular permission scoping for specific operations
  • Eliminates the need to share raw API credentials
  • Creates a consistent authentication experience across all supported exchanges
  • Enables secure token management through Bluvo’s infrastructure
Once you implement Bluvo’s OAuth2 flow, your users can connect their exchange accounts in seconds without technical knowledge, while you maintain complete security and compliance.

​
Implementation Flow

Bluvo’s OAuth2 implementation follows a secure three-step process that handles the complexities of exchange authentication while providing you with simple wallet IDs for trading operations.

​
Step 1: Request OAuth2 Popup URL

Your application requests a popup URL that will initiate the OAuth2 flow for a specific exchange: Request OAuth2 popup URL flow 
// Request OAuth2 popup URL for Coinbase
const  {url} = await client
    .oauth2
    .getLink(
        'coinbase',
        'random-uuid-1234', // walletId
    );

// Open popup window for user authentication
window.open(url, 'oauth2_popup', 'width=500,height=600');

​
Step 2: Listen for Authentication Completion

After the user completes authentication, you need to poll for the wallet ID or listen via WebSocket:

​
Option A: Polling Method

OAuth2 polling flow 
// Poll for authentication completion
const pollForWallet = async (worflowRunId: string) => {
    const maxAttempts = 30; // 30 seconds with 1-second intervals
    
    for (let attempt = 0; attempt < maxAttempts; attempt++) {
        try {
            const {
                id,
                walletId,
                details,
                status
            } = await client
                .workflow
                .get(workflowRunId, 'oauth2');
            
            if (status === 'completed') {
                return walletId; // Encrypted wallet ID
            }
            
            if (status === 'failed') {
                throw new Error('OAuth2 authentication failed');
            }
            
            // Wait 1 second before next attempt
            await new Promise(resolve => setTimeout(resolve, 1000));
        } catch (error) {
            console.error('Polling error:', error);
        }
    }
    
    throw new Error('OAuth2 authentication timeout');
};

​
Option B: WebSocket Method

OAuth2 WebSocket flow 
// Listen via WebSocket for real-time updates
const listenForWallet = (worflowRunId: string) => {
    client.subscribe(worflowRunId, 'oauth2', (message) => {
        const {
            id,
            walletId,
            details,
            status
         } = message;

        if (status === 'completed') {
            return walletId; // Encrypted wallet ID
        }

        if (status === 'failed') {
            throw new Error('OAuth2 authentication failed');
        }
    });
};

​
Step 3: Use Wallet ID for Trading Operations

Once you receive the wallet ID, you can use it for all trading operations without handling raw access tokens: 
// Use the encrypted wallet ID for trading
const {walletId} = await pollForWallet(workflowRunId);

// Execute trades using the wallet ID
const { workflowRunId } = await client.wallet.transaction.withdraw({
    walletId:           walletId,             // Your connected wallet’s ID
    amount:             15,                    // Amount to withdraw
    asset:              'USDT',                // Asset symbol (e.g., 'BTC', 'LTC')
    destinationAddress: RECEPIENT_ADDRESS,     // Recipient on-chain address
    network:            undefined,             // Optional: specify network if needed
    tag:                undefined,             // Optional: for assets requiring a tag (e.g., XRP, XLM)
});

​
Security Architecture

​
Wallet ID vs Access Token

A critical security feature of Bluvo’s OAuth2 implementation is that we never return raw access tokens to your application. Instead:
  • Access tokens are securely stored and encrypted within Bluvo’s infrastructure
  • Wallet IDs are returned to your application as opaque identifiers
  • Each wallet ID internally maps to the encrypted access token using our multi-tenant encryption system
  • Your application never handles or stores sensitive OAuth2 credentials
This architecture provides several security benefits: 
// What you DON'T get 👇
{
    "access_token": "ya29.AHES6ZTtm7SuokEB...", // Raw token exposed
    "refresh_token": "1/6BMfW9j...",            // Refresh token exposed
    "expires_in": 3600
}

// What you DO get 👇
{
    "walletId": "wallet_a1b2c3d4e5f6",          // Encrypted pointer stored in tenant-db for this customer
    "exchange": "coinbase",
    "permissions": ["read", "trade"],
    "created_at": "2024-01-15T10:30:00Z"
}

​
Encryption and Storage

Behind the scenes, Bluvo handles all token management:
  • Access tokens are encrypted using AES-256 with tenant-specific keys
  • Refresh tokens are automatically managed and can be used within 1 year of creation
  • Multi-tenant isolation ensures your tokens are completely separated from other customers

​
Benefits

Bluvo’s OAuth2 implementation provides these key advantages:

​
For Developers

  • Simplified integration with standardized OAuth2 flows across all supported exchanges
  • No credential management burden - just use wallet IDs for all operations
  • Automatic token refresh handled transparently by Bluvo
  • Consistent API regardless of underlying exchange OAuth2 variations

​
For End Users

  • Familiar authentication flow similar to “Login with Google”
  • Granular permissions with clear scope definitions
  • No API key creation or technical knowledge required
  • Instant connection with just a few clicks

​
For Security

  • Zero credential exposure to your application
  • Enterprise-grade encryption for all stored tokens
  • Multi-tenant isolation with physical data separation
  • Automatic security updates as exchange APIs evolve

​
Next Steps

Ready to implement OAuth2 authentication for your crypto application?