airweave / rules

---
description: Description of how the integrations yaml works.
globs: **/yaml/**
alwaysApply: false
---
# Airweave Integrations Configuration Structure

## YAML Configuration Structure
The `<env>.integrations.yaml` files define authentication configurations for various third-party service integrations. The structure follows this pattern:

```yaml
integrations:
  service_name:
    auth_type: "oauth2_with_refresh"  # or other auth types
    url: "https://service.com/oauth/authorize"
    backend_url: "https://service.com/oauth/token"
    grant_type: "authorization_code"
    client_id: "client_id_here"
    client_secret: "client_secret_here"
    content_type: "application/x-www-form-urlencoded"
    client_credential_location: "body"  # or "header"
    scope: "scope1 scope2 scope3"  # service-specific bot/app permissions
    user_scope: "user_scope1 user_scope2"  # optional, user-specific permissions (Slack, etc.)
    requires_pkce: false  # optional, default false. Set true for PKCE-required providers (e.g., Airtable)
    additional_frontend_params:  # optional service-specific parameters
      param1: "value1"
      param2: "value2"
```

### Example Integrations

**Standard OAuth (Gmail):**
```yaml
gmail:
  auth_type: "oauth2_with_refresh"
  url: "https://accounts.google.com/o/oauth2/auth"
  backend_url: "https://oauth2.googleapis.com/token"
  grant_type: "authorization_code"
  client_id: "502433363466-d8ruvkdb3nkafulj63tnenn8iud31sks.apps.googleusercontent.com"
  client_secret: "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"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "body"
  scope: "https://www.googleapis.com/auth/gmail.readonly"
  additional_frontend_params:
    access_type: "offline"
    prompt: "consent"
```

**OAuth with PKCE (Airtable):**
```yaml
airtable:
  oauth_type: "with_refresh"
  url: "https://airtable.com/oauth2/v1/authorize"
  backend_url: "https://airtable.com/oauth2/v1/token"
  grant_type: "authorization_code"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "header"
  scope: "schema.bases:read data.records:read"
  requires_pkce: true  # PKCE (Proof Key for Code Exchange) prevents authorization code interception
```

**PKCE Flow Details:**
When `requires_pkce: true`, the OAuth flow includes:
1. System generates a `code_verifier` (random string) during authorization
2. Computes `code_challenge` = SHA256(code_verifier) and sends in auth URL
3. Stores `code_verifier` in `init_session.overrides` for later retrieval
4. During token exchange, sends the original `code_verifier` to prove authenticity
5. Provider verifies SHA256(code_verifier) matches the original code_challenge

This prevents authorization code interception attacks by ensuring the token exchange request comes from the same client that initiated authorization.

**Microsoft Excel (Microsoft Graph API):**
```yaml
excel:
  oauth_type: "with_rotating_refresh"
  url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
  backend_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
  grant_type: "authorization_code"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "body"
  scope: "offline_access https://graph.microsoft.com/User.Read https://graph.microsoft.com/Files.Read.All"
  additional_frontend_params:
    response_type: "code"
    response_mode: "query"
```

**Key Requirements:**
- Uses Microsoft Graph API (v1.0) to access Excel files
- Requires `Files.Read.All` permission to read Excel workbooks from OneDrive/SharePoint
- Uses `with_rotating_refresh` token type (refresh tokens rotate on each refresh)
- Entity hierarchy: `Workbook → Worksheet → Table/Rows`

**Microsoft Word (Microsoft Graph API):**
```yaml
word:
  oauth_type: "with_rotating_refresh"
  url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
  backend_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
  grant_type: "authorization_code"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "body"
  scope: "offline_access https://graph.microsoft.com/User.Read https://graph.microsoft.com/Files.Read.All"
  additional_frontend_params:
    response_type: "code"
```

**Key Requirements:**
- Uses Microsoft Graph API (v1.0) to access Word documents
- Requires `Files.Read.All` permission to read Word files (.docx) from OneDrive/SharePoint
- Uses `with_rotating_refresh` token type (refresh tokens rotate on each refresh)
- Documents are treated as `FileEntity` objects: downloaded → converted to markdown → chunked → embedded
- Supports `.docx`, `.doc`, `.docm`, `.dotx`, `.dotm` file formats
- Test/monke environments require `Files.ReadWrite.All` for creating/deleting test documents

**Microsoft Teams (Microsoft Graph API):**
```yaml
teams:
  auth_type: "oauth2_with_refresh"
  url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
  backend_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
  grant_type: "authorization_code"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "body"
  scope: "offline_access User.Read Team.ReadBasic.All Channel.ReadBasic.All ChannelMessage.Read.All Chat.Read ChatMessage.Read Files.Read.All"
```

**Google Docs (Google Drive API):**
```yaml
google_docs:
  oauth_type: "with_refresh"
  url: "https://accounts.google.com/o/oauth2/auth"
  backend_url: "https://oauth2.googleapis.com/token"
  grant_type: "authorization_code"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  content_type: "application/x-www-form-urlencoded"
  client_credential_location: "body"
  scope: "https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/documents.readonly"
  additional_frontend_params:
    access_type: "offline"
    prompt: "consent"
```

**Key Requirements:**
- Uses Google Drive API to access Google Docs documents
- Requires `drive.readonly` permission to list and access documents
- Requires `documents.readonly` permission to read document content
- Documents are exported as DOCX format for processing
- Entity hierarchy: `GoogleDocsDocumentEntity` (FileEntity-based)

## Folder Structure
The files appear to be part of a structured monorepo with:

```
├── yaml/         # YAML integration configs
├── dev.integrations.yaml
└── prod.integrations.yaml
```

**OAuth1 Structure (e.g., Trello):**
```yaml
trello:
  oauth_type: "oauth1"  # Specifies OAuth1 instead of OAuth2
  request_token_url: "https://trello.com/1/OAuthGetRequestToken"
  authorization_url: "https://trello.com/1/OAuthAuthorizeToken"
  access_token_url: "https://trello.com/1/OAuthGetAccessToken"
  consumer_key: "your-consumer-key"
  consumer_secret: "@Microsoft.KeyVault(SecretUri=...)"
  scope: "read,write"  # Optional
  expiration: 8640000  # Optional, token lifetime in seconds
```

## Template URLs for Instance-Specific OAuth

Some integrations require per-customer endpoints (e.g., Zendesk subdomain):

```yaml
zendesk:
  auth_type: "oauth2_with_refresh"
  url: "https://{instance_url}/oauth/authorizations/new"
  backend_url: "https://{instance_url}/oauth/tokens"
  url_template: true  # Enable URL templating
  backend_url_template: true  # Enable backend URL templating
  # ... rest of config
```

Template variables are populated from the source's config class `get_template_config_fields()`.

Note that it is alphabetically sorted.