> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.airweave.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.airweave.ai/_mcp/server.

# Direct OAuth

## Overview

Direct OAuth allows you to create source connections using the standard OAuth 2.0 browser flow. This method provides a seamless user experience where users authenticate directly through their service provider's consent screen, without needing to manage tokens manually.

Airweave supports two main approaches for Direct OAuth:

1. **URL-based OAuth**: Users authenticate through Airweave's hosted OAuth flow
2. **BYOC (Bring Your Own Credentials)**: Use your own OAuth application credentials

## Supported Connectors

Direct OAuth is supported by most Airweave connectors. Some connectors require you to provide your own OAuth application credentials (BYOC), while others can use Airweave's hosted OAuth flow.

**Connectors requiring BYOC:**

* Dropbox, Gmail, Google Calendar, Google Drive

**Connectors using Direct Authentication only:**

* Bitbucket, GitHub, PostgreSQL, Stripe, CTTI

Most connectors also support authentication through external providers like Composio and Pipedream.

## URL-based OAuth Flow

The URL-based OAuth flow is the simplest way to connect sources. Users are redirected to Airweave's hosted OAuth flow, which handles the entire authentication process.

### How it works

1. **Initiate Connection**: Create a source connection using the URL-based authentication method. The response includes a `claim_token` that you must store for the verification step.
2. **User Consent**: Users are redirected to the service provider's consent screen
3. **Token Exchange**: Airweave exchanges the authorization code for access and refresh tokens
4. **Verify Ownership**: After the OAuth callback completes, call `POST /source-connections/{id}/verify-oauth` with the `claim_token` to prove your client initiated the flow. This triggers data synchronization.

### Creating a URL-based OAuth connection

```Python title="Python"
from airweave import AirweaveSDK
from airweave.types import OAuthBrowserAuthentication

airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")

# Create source connection - returns pending connection with auth_url
source_connection = airweave.source_connections.create(
    name="Notion connection",
    short_name="notion",
    readable_collection_id="my-collection-id",
    authentication=OAuthBrowserAuthentication(
        redirect_uri="https://your-app.com/callback"
    ),
    sync_immediately=False  # OAuth browser flows cannot sync immediately
)

# Connection is now in pending state - redirect user to auth_url
print(f"Redirect user to: {source_connection.auth.auth_url}")
print(f"Connection status: {source_connection.status}")  # "pending"
print(f"Authenticated: {source_connection.auth.authenticated}")  # False
```

```javascript title="Node.js"
import { AirweaveSDKClient } from "@airweave/sdk";

const airweave = new AirweaveSDKClient({apiKey: "YOUR_API_KEY", baseUrl: "https://api.airweave.ai"});

// Create source connection - returns pending connection with auth_url
const sourceConnection = await airweave.sourceConnections.create({
    name: "Notion connection",
    shortName: "notion",
    readableCollectionId: "my-collection-id",
    authentication: {
        redirect_uri: "https://your-app.com/callback"
    },
    syncImmediately: false  // OAuth browser flows cannot sync immediately
});

// Connection is now in pending state - redirect user to auth_url
console.log(`Redirect user to: ${sourceConnection.auth.auth_url}`);
console.log(`Connection status: ${sourceConnection.status}`);  // "pending"
console.log(`Authenticated: ${sourceConnection.auth.authenticated}`);  // false
```

```bash title="cURL"
curl -X POST https://api.airweave.ai/source-connections \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Notion connection",
  "short_name": "notion",
  "readable_collection_id": "my-collection-id",
  "authentication": {
    "redirect_uri": "https://your-app.com/callback"
  },
  "sync_immediately": false
}'

# Response includes:
# {
#   "id": "connection-id",
#   "status": "pending",
#   "auth": {
#     "authenticated": false,
#     "auth_url": "https://api.airweave.ai/oauth/proxy/...",
#     "auth_url_expires": "2024-01-01T12:00:00Z"
#   }
# }
```

### Handling the OAuth callback

When using URL-based OAuth, you'll receive an authorization URL that you need to redirect users to. After they complete the OAuth flow, they'll be redirected back to your specified callback URL with the necessary parameters.

**Important**: OAuth browser flows (both standard and BYOC) cannot use `sync_immediately=true`. After the user completes the OAuth consent screen, you must call the `verify-oauth` endpoint with the `claim_token` from the create response to trigger data synchronization. Setting `sync_immediately=true` will result in a validation error.

### Verifying the OAuth flow

After the OAuth callback completes and the user is redirected back to your application, call the verify-oauth endpoint with the `claim_token` received during connection creation. This proves your client initiated the flow and triggers the data sync.

```Python title="Python"
# After user completes OAuth and is redirected back:
airweave.source_connections.verify_oauth(
    id=source_connection.id,
    claim_token=source_connection.auth.claim_token,
)
```

```javascript title="Node.js"
// After user completes OAuth and is redirected back:
await airweave.sourceConnections.verifyOauth(
    sourceConnection.id,
    { claimToken: sourceConnection.auth.claimToken }
);
```

```bash title="cURL"
# After user completes OAuth and is redirected back:
curl -X POST https://api.airweave.ai/source-connections/{connection-id}/verify-oauth \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "claim_token": "<claim_token from create response>"
}'
```

### Redirect URI basics

The `redirect_uri` is the URL where the user is sent after granting consent with the provider. It must exactly match an allowed redirect/callback URL configured for the OAuth app. Use it when you want users to return to your application after authentication (typical for hosted OAuth). For BYOC, configure the provider to allow Airweave's callback (`https://api.airweave.ai/oauth/callback`) and optionally set `redirect_uri` so Airweave can forward the user back to your app after the token exchange.

## BYOC (Bring Your Own Credentials)

BYOC allows you to use your own OAuth application credentials instead of Airweave's hosted OAuth flow. This gives you more control over the authentication process and branding.

### Benefits of BYOC

* **Custom Branding**: Use your own OAuth application with your branding
* **Enhanced Security**: Control your own OAuth application settings
* **Compliance**: Meet specific compliance requirements for your organization
* **Rate Limits**: Use your own rate limits instead of shared ones

### Setting up BYOC

To use BYOC, you'll need to:

1. **Create OAuth Application**: Set up an OAuth application with the service provider
2. **Configure Redirect URI**: Add Airweave's callback URL to your OAuth application
3. **Provide Credentials**: Use your client ID and client secret in the connection

### How BYOC Detection Works

BYOC (Bring Your Own Credentials) is automatically detected when you provide both `client_id` and `client_secret` in the `OAuthBrowserAuthentication` object. If you provide only one of these fields, the API will return a validation error.

**BYOC Detection Logic:**

* ✅ Both `client_id` AND `client_secret` provided → BYOC mode
* ✅ Neither `client_id` nor `client_secret` provided → Standard OAuth browser flow
* ❌ Only `client_id` OR only `client_secret` provided → Validation error

### Creating a BYOC connection

```Python title="Python"
from airweave import AirweaveSDK
from airweave.types import OAuthBrowserAuthentication

airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")

source_connection = airweave.source_connections.create(
    name="Notion connection (BYOC)",
    short_name="notion",
    readable_collection_id="my-collection-id",
    authentication=OAuthBrowserAuthentication(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        redirect_uri="https://your-app.com/callback"
    ),
    sync_immediately=False  # BYOC flows cannot sync immediately
)
```

```javascript title="Node.js"
import { AirweaveSDKClient } from "@airweave/sdk";

const airweave = new AirweaveSDKClient({apiKey: "YOUR_API_KEY", baseUrl: "https://api.airweave.ai"});

const sourceConnection = await airweave.sourceConnections.create({
    name: "Notion connection (BYOC)",
    shortName: "notion",
    readableCollectionId: "my-collection-id",
    authentication: {
        client_id: "YOUR_CLIENT_ID",
        client_secret: "YOUR_CLIENT_SECRET",
        redirect_uri: "https://your-app.com/callback"
    },
    syncImmediately: false  // BYOC flows cannot sync immediately
});
```

```bash title="cURL"
curl -X POST https://api.airweave.ai/source-connections \
     -H "x-api-key: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Notion connection (BYOC)",
  "short_name": "notion",
  "readable_collection_id": "my-collection-id",
  "authentication": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://your-app.com/callback"
  },
  "sync_immediately": false
}'
```

## OAuth Application Setup

### Required Redirect URIs

When setting up your OAuth application for BYOC, you'll need to add Airweave's callback URL as an allowed redirect URI:

```
https://api.airweave.ai/oauth/callback
```

### Required Scopes

Each connector requires specific OAuth scopes to function properly. Check the individual connector documentation for the required scopes.

### Example: GitHub OAuth Application Setup

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Click "New OAuth App"
3. Fill in the application details:
   * **Application name**: Your application name
   * **Homepage URL**: Your application URL
   * **Authorization callback URL**: `https://api.airweave.ai/oauth/callback`
4. Note down the Client ID and Client Secret for use in your BYOC connection

### Getting Help

If you encounter issues not covered in this documentation, please reach out to us at **[hello@airweave.ai](mailto:hello@airweave.ai)** or check our [API Reference](/api-reference) for more detailed information about the OAuth endpoints.