White Labeling

Airweave’s white labeling feature enables you to create multi-tenant integrations that maintain data isolation and security while providing a seamless experience for your users.

This allows you to give customers a simple way to hand off their data to you.

Overview

White labeling in Airweave allows you to:

• Manage OAuth2 flows for multiple tenants
• Maintain data isolation between tenants

Example Workflow

1. Customer clicks “Connect to Service” in your app
2. Airweave handles OAuth2 authorization
3. Tokens are securely stored and linked to tenant
4. Data sync begins automatically
5. Your app queries data using tenant metadata

How It Works

Token Management

After the OAuth2 flow completes, Airweave:

1. Securely stores tokens:

   • Access tokens for API authentication
   • Refresh tokens for automatic token renewal
   • Links tokens to your provided tenant metadata

2. Handles token lifecycle:

   • Automatically refreshes expired access tokens
   • Maintains uninterrupted synchronization
   • Manages API authentication behind the scenes

Setting Up White Label Integration

1. White Label Configuration

First, create a white label configuration either through the UI or programmatically.

Option A: Using the Airweave UI

Option B: Using the SDK

1
import { AirweaveSDK } from "@airweave/sdk";
2
3
const client = new AirweaveSDK({
4
  apiKey: "your-api-key",
5
});
6
7
const integration = await client.whiteLabels.create({
8
  name: "Custom Integration",
9
  sourceId: "source-uuid", // UUID of the source to connect to
10
  redirectUrl: "https://your-app.com/oauth/callback",
11
  clientId: "your-oauth-client-id",
12
  clientSecret: "your-oauth-client-secret",
13
});

2. Initiating OAuth2 Flow

Create a component that redirects users to the OAuth2 authorization screen:

1
import { Button } from "@/components/ui/button";
2
import { useApiClient } from "@/lib/api";
3
import { useRouter } from "next/router";
4
import { ExternalLink } from "lucide-react";
5
6
interface ConnectSourceProps {
7
  sourceId: string;
8
  organizationId: string;
9
}
10
11
export function ConnectSource({ sourceId, organizationId }: ConnectSourceProps) {
12
  const apiClient = useApiClient();
13
  const router = useRouter();
14
15
  const handleConnect = async () => {
16
    try {
17
      const { authUrl } = await apiClient.whiteLabels.getOauth2AuthUrl({
18
        whiteLabelId: integration.id,
19
        state: organizationId,
20
      });
21
      
22
      router.push(authUrl);
23
    } catch (error) {
24
      console.error("Failed to get auth URL:", error);
25
    }
26
  };
27
28
  return (
29
    <Button 
30
      onClick={handleConnect}
31
      variant="outline"
32
    >
33
      Connect Source <ExternalLink className="ml-2 h-4 w-4" />
34
    </Button>
35
  );
36
}

3. Handling OAuth2 Callback

Create a callback handler component to process the OAuth2 response:

1
interface CallbackProps {
2
  whiteLabelId: string;
3
}
4
5
export function OAuthCallback({ whiteLabelId }: CallbackProps) {
6
  const apiClient = useApiClient();
7
  const router = useRouter();
8
  const { code, state } = router.query;
9
10
  useEffect(() => {
11
    const handleCallback = async () => {
12
      if (!code || !state) return;
13
14
      try {
15
        await apiClient.whiteLabels.exchangeOauth2Code({
16
          whiteLabelId,
17
          code: code as string,
18
          metadata: {
19
            organizationId: state as string,
20
          },
21
        });
22
23
        router.push('/integrations/success');
24
      } catch (error) {
25
        console.error('OAuth callback failed:', error);
26
        router.push('/integrations/error');
27
      }
28
    };
29
30
    handleCallback();
31
  }, [code, state, whiteLabelId, apiClient, router]);
32
33
  return (
34
    <div className="flex items-center justify-center min-h-screen">
35
      <div className="text-center">
36
        <h2 className="text-lg font-semibold mb-2">Connecting your account...</h2>
37
        <p className="text-muted-foreground">Please wait while we complete the setup.</p>
38
      </div>
39
    </div>
40
  );
41
}

Data Synchronization

Once authentication is complete, Airweave:

1. Processes data efficiently:

   • Runs incremental syncs to fetch only new/updated data
   • Entities data for optimal processing
   • Applies versioning and computes hashes for deduplication

2. Maintains tenant isolation:

   • Uses your provided metadata (organization ID, user details) to isolate data
   • Ensures secure multi-tenant operations
   • Enables tenant-specific data enrichment

Architecture

The architecture diagram above illustrates how Airweave handles different authentication methods across multiple data sources:

• API Key Integration: Users (like User A) can connect services that use API key authentication (e.g., Slack)
• OAuth Integration: Users (like User B) can connect services that require OAuth authentication (e.g., Google Drive, Notion)
• Database Integration: Users (like User C) can connect directly to databases using JDBC credentials

All these connections are managed through Airweave’s white-labeling system, which:

1. Securely stores and manages credentials
2. Maintains strict tenant isolation
3. Handles authentication renewals automatically
4. Synchronizes data to your agent while preserving tenant context

This architecture ensures that regardless of the authentication method, all data is properly isolated and securely managed while providing a unified interface for your application.