Airweave Connect

Airweave Connect is a hosted, embeddable UI widget that lets end users connect their apps (Slack, GitHub, Google Drive, Notion, and more) directly inside your product. Think of it like Plaid for data integrations: you add a button, your users click it, and their data starts syncing.

How it works

The widget runs inside an iframe hosted by Airweave. Your backend creates a short-lived session token, your frontend passes it to the widget via postMessage, and the widget handles the rest.

┌────────────────────────────────────────────────────────────────┐
│  Your Application                                              │
│                                                                │
│   [Connect your apps]  ──onClick──►  Airweave Connect modal   │
│                                      ┌──────────────────────┐  │
│                                      │  ● Slack             │  │
│                                      │  ● GitHub            │  │
│                                      │  ● Google Drive      │  │
│                                      │  ...                 │  │
│                                      └──────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

The flow in three steps:

Quickstart

1. Create a Connect session (server-side)

Your backend creates a session token by calling the Airweave API with your API key. Never expose your API key to the browser.

1
import requests
2
3
def create_connect_session(collection_id: str, user_id: str) -> str:
4
    response = requests.post(
5
        "https://api.airweave.ai/connect/sessions",
6
        headers={
7
            "X-API-Key": "YOUR_API_KEY",
8
            "Content-Type": "application/json",
9
        },
10
        json={
11
            "readable_collection_id": collection_id,
12
            "mode": "all",
13
            "end_user_id": user_id,
14
        },
15
    )
16
    return response.json()["session_token"]

The response contains the session token:

1
{
2
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
3
  "session_token": "eyJ...",
4
  "expires_at": "2024-01-01T00:10:00Z"
5
}

2. Add the Connect widget (client-side)

Choose the integration method that fits your stack:

$
npm install @airweave/connect-react

1
import { useAirweaveConnect } from "@airweave/connect-react";
2
3
export function ConnectButton() {
4
  const { open, isLoading } = useAirweaveConnect({
5
    getSessionToken: async () => {
6
      // Call your backend. Never hardcode API keys here.
7
      const res = await fetch("/api/airweave/session", { method: "POST" });
8
      const data = await res.json();
9
      return data.session_token;
10
    },
11
    onSuccess: (connectionId) => {
12
      console.log("New connection created:", connectionId);
13
    },
14
    onClose: (reason) => {
15
      console.log("Modal closed:", reason); // "success" | "cancel" | "error"
16
    },
17
  });
18
19
  return (
20
    <button onClick={open} disabled={isLoading}>
21
      {isLoading ? "Loading..." : "Connect your apps"}
22
    </button>
23
  );
24
}

Session modes

The mode parameter controls what users can do inside the widget:

Use connect when onboarding new users, manage for a settings page, and reauth when a connection needs its credentials refreshed.

Restricting integrations

Use allowed_integrations to limit which sources appear in the widget. Pass a list of connector short names:

1
{
2
  "readable_collection_id": "my-collection-abc123",
3
  "mode": "connect",
4
  "allowed_integrations": ["slack", "github", "google_drive", "notion"]
5
}

If allowed_integrations is omitted, all available connectors are shown.

Theme customization

Pass a theme object to match the widget to your brand. Supports separate palettes for dark and light modes.

1
const { open } = useAirweaveConnect({
2
  getSessionToken,
3
  theme: {
4
    mode: "dark", // "light" | "dark" | "system"
5
    colors: {
6
      dark: {
7
        primary: "#6366f1",
8
        background: "#0f172a",
9
        surface: "#1e293b",
10
        text: "#ffffff",
11
        textMuted: "#9ca3af",
12
        border: "#334155",
13
        success: "#22c55e",
14
        error: "#ef4444",
15
      },
16
      light: {
17
        primary: "#4f46e5",
18
        background: "#ffffff",
19
        surface: "#f8fafc",
20
        text: "#1f2937",
21
        textMuted: "#6b7280",
22
        border: "#e5e7eb",
23
        success: "#22c55e",
24
        error: "#ef4444",
25
      },
26
    },
27
  },
28
});

You can also update the theme while the modal is open:

1
const { setTheme } = useAirweaveConnect({ getSessionToken });
2
3
// Call at any time, takes effect immediately
4
setTheme({ mode: "light" });

Event callbacks

SDK reference

React: useAirweaveConnect(options)

Options:

Returns:

Vanilla JS: new AirweaveConnect(config)

The AirweaveConnect class accepts the same options as the React hook. Key methods:

Session API reference

POST /connect/sessions

Creates a Connect session. Requires an API key.

Request body:

Response:

Security

• Session tokens are HMAC-signed and expire after 10 minutes. Create a new token for each modal open. The SDKs handle this automatically.
• API keys must only be used server-side. Never include them in frontend code or responses.
• Collection scoping: the collection is bound to the session at creation time. The widget cannot escalate to other collections.
• allowed_integrations lets you restrict which connectors are visible, reducing your attack surface.
• Origin validation: the Connect widget validates postMessage origins. Once it receives the first token from your app, it only accepts subsequent messages from that same origin.

Self-hosting

If you’re running Airweave on your own infrastructure, set connectUrl to point at your self-hosted Connect widget:

1
const { open } = useAirweaveConnect({
2
  getSessionToken,
3
  connectUrl: "https://connect.your-domain.com",
4
});

You’ll also need to point the Connect widget’s API_URL environment variable at your self-hosted Airweave API:

$
docker run -p 8082:8082 \
>
  -e API_URL=https://api.your-domain.com \
>
  ghcr.io/airweave-ai/connect:latest

Try it in the playground

The Connect Playground in the Airweave dashboard lets you configure a session, customize the theme, pick allowed integrations, and preview the widget before writing a line of code. It also generates ready-to-use backend and frontend snippets you can copy directly into your app.