Docs

Direct Token Authentication

Connect OAuth2 sources by providing tokens directly

Need to connect OAuth2 sources programmatically? Skip the UI flow and provide your tokens directly! Perfect for CI/CD pipelines, custom integrations, and when you need full control over authentication.

✨ Two Ways to Authenticate

UI Flow: Let Airweave handle OAuth2 automatically through the dashboard Direct Tokens: Provide your own tokens via API calls for maximum control

Why Use Direct Token Authentication?

Programmatic Control

Perfect for CI/CD pipelines and automated workflows that need OAuth2 sources

Custom Integration

When you’re building custom auth flows or managing tokens externally

Multi-Tenant Apps

Connect different user accounts without going through Airweave’s UI each time

Quick Overview

Airweave supports two authentication approaches for OAuth2 sources:

  1. 🖥️ UI-Based Flow: Users authenticate through the web interface - Airweave handles everything
  2. ⚡ Direct Injection: You provide tokens directly via API calls - full programmatic control

Most users should use the UI flow! It’s simpler and Airweave handles token refresh automatically. Only use direct injection when you need programmatic control.

How It Works

1

Get Your Tokens

Obtain OAuth2 tokens from your target service (outside of Airweave)

2

Create Connection

Pass tokens in the auth_fields when creating your source connection

3

Automatic Management

Airweave stores tokens securely and handles refresh automatically

Creating Connections with Direct Tokens

Endpoint: POST /source-connections/

Authentication Schema

The endpoint accepts a SourceConnectionCreate object. For direct token authentication, provide the auth_fields parameter with your OAuth2 credentials.

Token Requirements

Authentication fields must exactly match the source’s configuration. Check backend/airweave/platform/configs/auth.py for field names.

Complete Example

Here’s how to create an Asana connection with direct tokens:

Create Asana Connection
$curl -X POST "https://api.airweave.ai/source-connections/" \
>  -H "Content-Type: application/json" \
>  -H "x-api-key: YOUR_API_KEY" \
>  -d '{
>    "name": "My Asana Connection",
>    "short_name": "asana",
>    "collection": "my-collection",
>    "auth_fields": {
>      "access_token": "1/1234567890abcdef...",
>      "refresh_token": "1/9876543210fedcba..."
>    },
>    "sync_immediately": true
>  }'

What Happens Next

Airweave encrypts and stores your tokens securely in the credential store. They’re never exposed in logs or API responses.

For sources with refresh tokens, Airweave automatically refreshes access tokens when they expire - no intervention needed.

Airweave validates that required fields are provided but doesn’t verify token validity at creation time. Invalid tokens will cause sync failures.

Token Override for Sync Jobs

Sometimes you need to run a sync with different credentials without changing the stored connection. Perfect for testing or user impersonation!

Endpoint: POST /source-connections/{connection_id}/run

Standard vs Override Behavior

📋 Standard Behavior

Uses stored credentials and automatically refreshes tokens as needed

⚡ Token Override

Uses your provided token for this sync only - doesn’t change stored credentials

Override Examples

Run with Token Override
$curl -X POST "https://api.airweave.ai/source-connections/12345/run" \
>  -H "Content-Type: application/json" \
>  -H "x-api-key: YOUR_API_KEY" \
>  -d '{
>    "access_token": "temporary-token-for-this-sync..."
>  }'

Use Cases for Token Override

🧪 Testing

Validate sync behavior with different user credentials without updating the connection

⏱️ Temporary Access

Use short-lived tokens without updating stored credentials

👥 User Impersonation

Run syncs on behalf of specific users in multi-tenant scenarios

Important Limitations
  • OAuth2 sources only - Token override only works with OAuth2 authentication
  • Single-use - The token applies only to the current sync job
  • No refresh - Airweave won’t attempt to refresh the provided access token
  • Ensure validity - Make sure the token has necessary permissions and hasn’t expired

Error Handling & Troubleshooting

Common error scenarios and how to fix them:

Problem: Invalid or missing authentication fields

Solutions:

  • Check that all required fields are provided
  • Verify field names match the source’s auth configuration
  • Ensure tokens are properly formatted

Problem: Source type not found or connection doesn’t exist

Solutions:

  • Verify the short_name matches an available source
  • Check that the connection ID exists
  • Ensure you have access to the connection

Problem: Token refresh failed during sync execution

Solutions:

  • Verify tokens are valid and not expired
  • Check that tokens have required permissions
  • Ensure refresh token is still valid

Best Practices

🔒 Security First

Never hardcode tokens in source code or config files Use environment variables or secure credential stores Rotate tokens regularly for enhanced security

📊 Monitoring

Monitor sync status to detect authentication failures quickly Test tokens in development before production use Set up alerts for failed syncs due to auth issues

💡 Pro Tip

Use stored credentials when possible! The standard OAuth2 flow provides better token management and is more reliable for long-term use.

Common OAuth2 Sources

Here are the exact auth_fields required for popular sources:

1{
2  "access_token": "ya29.a0AfH6SMBxxxxxx...",
3  "refresh_token": "1//0GxxxxxxxxxxxxxxV8",
4  "client_id": "123456789-abc.apps.googleusercontent.com",
5  "client_secret": "GOCSPX-xxxxxxxxxxxxxxxx"
6}
1{
2  "access_token": "EwBwA8l6BAAUsxxxxxxxxxxxxxxx",
3  "refresh_token": "M.C525_SNy.xxxxxxxxxxxxxx"
4}
1{
2  "access_token": "1/1234567890:abcdefghij",
3  "refresh_token": "1/9876543210:zyxwvutsrq"
4}
1{
2  "access_token": "xoxb-1234567890-abcdefghij"
3}
Slack uses non-expiring tokens, so no refresh token is needed.
1{
2  "access_token": "ntn_abcdefghijklmnop123456789"
3}
Notion uses non-expiring tokens.

Alternative: White Label Integration

Building a multi-tenant application? Consider White Label Integration instead! It lets Airweave handle the OAuth2 flow while maintaining your branding.

Learn About White Labeling

Perfect for SaaS applications that need OAuth2 with custom branding

Reference

  • Authentication configurations: backend/airweave/platform/configs/auth.py
  • Source connection schema: backend/airweave/schemas/source_connection.py
  • API documentation: Available at /docs endpoint on your Airweave instance

Next Steps

🔌 Browse All Connectors

See authentication requirements for all 28+ sources

🚀 Return to Quickstart

Continue with the quickstart guide

🤖 Connect AI Agents

Use your connected data with AI agents

💬 Get Support

Join our community for help and discussions