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

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

1
from airweave import AirweaveSDK
2
from airweave.types import OAuthBrowserAuthentication
3
4
airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")
5
6
# Create source connection - returns pending connection with auth_url
7
source_connection = airweave.source_connections.create(
8
    name="Notion connection",
9
    short_name="notion",
10
    readable_collection_id="my-collection-id",
11
    authentication=OAuthBrowserAuthentication(
12
        redirect_uri="https://your-app.com/callback"
13
    ),
14
    sync_immediately=False  # OAuth browser flows cannot sync immediately
15
)
16
17
# Connection is now in pending state - redirect user to auth_url
18
print(f"Redirect user to: {source_connection.auth.auth_url}")
19
print(f"Connection status: {source_connection.status}")  # "pending"
20
print(f"Authenticated: {source_connection.auth.authenticated}")  # False

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.

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.

1
# After user completes OAuth and is redirected back:
2
airweave.source_connections.verify_oauth(
3
    id=source_connection.id,
4
    claim_token=source_connection.auth.claim_token,
5
)

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

1
from airweave import AirweaveSDK
2
from airweave.types import OAuthBrowserAuthentication
3
4
airweave = AirweaveSDK(api_key="YOUR_API_KEY", base_url="https://api.airweave.ai")
5
6
source_connection = airweave.source_connections.create(
7
    name="Notion connection (BYOC)",
8
    short_name="notion",
9
    readable_collection_id="my-collection-id",
10
    authentication=OAuthBrowserAuthentication(
11
        client_id="YOUR_CLIENT_ID",
12
        client_secret="YOUR_CLIENT_SECRET",
13
        redirect_uri="https://your-app.com/callback"
14
    ),
15
    sync_immediately=False  # BYOC flows cannot sync immediately
16
)

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 or check our API Reference for more detailed information about the OAuth endpoints.