Feishu/Lark Connector #

The Feishu/Lark connector indexes cloud documents from Feishu and Lark, including documents, spreadsheets, mind notes, multi-dimensional tables, and knowledge bases.

Features #

• 🔍 Smart Search: Keyword-based search for cloud documents
• 📚 Multiple Document Types: Support for doc, sheet, slides, mindnote, bitable, file, docx, folder, shortcut
• 🔐 Dual Authentication: OAuth 2.0 and user access token authentication (choose one)
• ⚡ Efficient Sync: Scheduled and manual synchronization
• 🔄 Recursive Search: Automatically search folder contents recursively
• 🔄 Token Auto-refresh: OAuth authentication supports automatic refresh of access_token and refresh_token
• 🌐 Dynamic Redirect: Supports dynamic OAuth redirect URI construction for multi-environment deployment
• 🏗️ Unified Architecture: Feishu and Lark share base implementation with 95% code reuse
• 📁 Directory Access: Hierarchical browsing based on Feishu’s original folder structure; folder directories are created on-the-fly
• 🕒 Incremental Sync: Robust last-modified tracking with safety buffer to avoid edge misses

Supported Platforms #

Feishu #

• Domain: open.feishu.cn / accounts.feishu.cn
• Connector ID: feishu
• Region: Mainland China

Lark #

• Domain: open.larksuite.com / accounts.larksuite.com
• Connector ID: lark
• Region: Overseas regions

Authentication Methods #

The Feishu/Lark connector supports two authentication methods. You must choose one:

1. OAuth 2.0 Authentication (Recommended) #

Uses OAuth flow to automatically obtain user access tokens with automatic refresh support and expiration time management.

Requirements #

• client_id: Feishu/Lark app Client ID
• client_secret: Feishu/Lark app Client Secret
• document_types: List of document types to synchronize

Authentication Flow #

1. User creates Feishu/Lark datasource with client_id and client_secret
2. Clicks “Connect” button, system redirects to Feishu/Lark authorization page
3. User completes authorization, system automatically obtains access_token and refresh_token
4. System automatically updates datasource configuration with complete OAuth information and expiration times

Advantages #

• High security, no manual token management required
• Automatic access_token and refresh_token refresh support
• Automatic token expiration time management
• Automatic user information retrieval
• Compliant with OAuth 2.0 standards
• Supports multi-environment deployment (dynamic redirect URI)

2. User Access Token Authentication (Alternative) #

Directly uses user access tokens, suitable for scenarios with existing tokens.

Requirements #

• user_access_token: User’s access token
• document_types: List of document types to synchronize

Use Cases #

• Already have valid user access tokens
• Don’t want to use OAuth flow
• Testing or development environments

Considerations #

• Manual token expiration management required
• Manual token updates needed after expiration
• Relatively lower security

Feishu/Lark App Permission Configuration #

Required Permissions #

The Feishu/Lark connector requires the following permissions to function properly:

Permission Application Steps #

Feishu App #

1. Login to Feishu Open Platform

   • Visit https://open.feishu.cn/
   • Login with Feishu account

2. Create Application

   • Click “Create Application”
   • Select “Enterprise Self-built Application”
   • Fill in application name and description

3. Apply for Permissions

   • Go to “Permission Management” page
   • Search and add the three permissions above
   • Submit permission application

4. Publish Application

   • After completing permission application, publish application to enterprise
   • Record the app’s Client ID and Client Secret

Lark App #

1. Login to Lark Open Platform

   • Visit https://open.larksuite.com/
   • Login with Lark account

2. Create Application

   • Click “Create Application”
   • Select “Enterprise Self-built Application”
   • Fill in application name and description

3. Apply for Permissions

   • Go to “Permission Management” page
   • Search and add the three permissions above
   • Submit permission application

4. Publish Application

   • After completing permission application, publish application to enterprise
   • Record the app’s Client ID and Client Secret

Permission Description #

• drive:drive: This is the core permission for accessing cloud documents, allowing the app to read user’s documents, spreadsheets, slides, and other files
• space:document:retrieve: Used to access documents in knowledge bases and spaces, expanding document access scope
• offline_access: Allows the app to access resources when user is offline, which is crucial for background sync tasks

Configuration Architecture #

Connector Level (OAuth Configuration) #

The OAuth configuration is now managed at the connector level. This provides better security and centralized management.

Feishu Connector Configuration #

connector:
  feishu:
    enabled: true
    interval: "30s"
    page_size: 100
    config:
      # OAuth Configuration (Required for OAuth flow)
      auth_url: "https://accounts.feishu.cn/open-apis/authen/v1/authorize"
      token_url: "https://open.feishu.cn/open-apis/authen/v2/oauth/token"
      redirect_url: "/connector/feishu/oauth_redirect"
      client_id: "cli_xxxxxxxxxxxxxxxx"
      client_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      document_types: ["doc", "sheet", "slides", "mindnote", "bitable", "file", "docx", "folder", "shortcut"]
      user_access_token: ""  # Optional, for direct token authentication

Lark Connector Configuration #

connector:
  lark:
    enabled: true
    interval: "30s"
    page_size: 100
    config:
      # OAuth Configuration (Required for OAuth flow)
      auth_url: "https://accounts.larksuite.com/open-apis/authen/v1/authorize"
      token_url: "https://open.larksuite.com/open-apis/authen/v2/oauth/token"
      redirect_url: "/connector/lark/oauth_redirect"
      client_id: "cli_xxxxxxxxxxxxxxxx"
      client_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      document_types: ["doc", "sheet", "slides", "mindnote", "bitable", "file", "docx", "folder", "shortcut"]
      user_access_token: ""  # Optional, for direct token authentication

Datasource Level (Auto-generated) #

When using OAuth authentication, datasources are automatically created during the OAuth flow. The system automatically generates:

Auto-generated Feishu Datasource #

datasource:
  id: "auto-generated-id"
  name: "User's Feishu"  # Auto-generated based on user profile
  type: "connector"
  enabled: true
  sync:
    enabled: true
  connector:
    id: "feishu"
    config:
      # OAuth tokens (auto-filled during OAuth flow)
      access_token: "u-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      refresh_token: "r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      token_expiry: "2024-01-01T12:00:00Z"
      refresh_token_expiry: "2024-01-31T12:00:00Z"
      profile:
        user_id: "ou_xxxxxxxxxxxxxxxx"
        name: "User Name"
        email: "user@example.com"

Auto-generated Lark Datasource #

datasource:
  id: "auto-generated-id"
  name: "User's Lark"  # Auto-generated based on user profile
  type: "connector"
  enabled: true
  sync:
    enabled: true
  connector:
    id: "lark"
    config:
      # OAuth tokens (auto-filled during OAuth flow)
      access_token: "u-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      refresh_token: "r-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      token_expiry: "2024-01-01T12:00:00Z"
      refresh_token_expiry: "2024-01-31T12:00:00Z"
      profile:
        user_id: "ou_xxxxxxxxxxxxxxxx"
        name: "User Name"
        email: "user@example.com"

Register Connectors #

Register Feishu Connector #

curl -XPUT "http://localhost:9000/connector/feishu?replace=true" -d '{
  "name": "Feishu Connector",
  "description": "Index Feishu cloud documents with OAuth 2.0 support.",
  "icon": "/assets/connector/feishu/icon.png",
  "category": "cloud_storage",
  "tags": ["feishu", "docs", "cloud"],
  "url": "http://coco.rs/connectors/feishu",
  "assets": {"icons": {"default": "/assets/connector/feishu/icon.png"}},
  "oauth_connect_implemented": true,
  "path_hierarchy": true,
  "processor": {
    "enabled": true,
    "name": "feishu"
  },
  "config": {
    "auth_url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
    "token_url": "https://open.feishu.cn/open-apis/authen/v2/oauth/token",
    "client_id": "cli_xxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}'

Register Lark Connector #

curl -XPUT "http://localhost:9000/connector/lark?replace=true" -d '{
  "name": "Lark Connector",
  "description": "Index Lark cloud documents with OAuth 2.0 support.",
  "icon": "/assets/connector/lark/icon.png",
  "category": "cloud_storage",
  "tags": ["lark", "docs", "cloud"],
  "url": "http://coco.rs/connectors/lark",
  "assets": {"icons": {"default": "/assets/connector/lark/icon.png"}},
  "oauth_connect_implemented": true,
  "path_hierarchy": true,
  "processor": {
    "enabled": true,
    "name": "lark"
  },
  "config": {
    "auth_url": "https://accounts.larksuite.com/open-apis/authen/v1/authorize",
    "token_url": "https://open.larksuite.com/open-apis/authen/v2/oauth/token",
    "client_id": "cli_xxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}'

Use feishu or lark as the unique connector ID.

Connector Configuration #

OAuth credentials are configured at the connector level via the management interface or API.

Feishu Connector #

{
  "id": "feishu",
  "name": "飞书云文档连接器",
  "builtin": true,
  "oauth_connect_implemented": true,
  "processor": {
    "enabled": true,
    "name": "feishu"
  },
  "config": {
    "client_id": "cli_xxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_url": "https://accounts.feishu.cn/open-apis/authen/v1/authorize",
    "token_url": "https://open.feishu.cn/open-apis/authen/v2/oauth/token"
  }
}

Lark Connector #

{
  "id": "lark",
  "name": "Lark Document Connector",
  "builtin": true,
  "oauth_connect_implemented": true,
  "processor": {
    "enabled": true,
    "name": "lark"
  },
  "config": {
    "client_id": "cli_xxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "auth_url": "https://accounts.larksuite.com/open-apis/authen/v1/authorize",
    "token_url": "https://open.larksuite.com/open-apis/authen/v2/oauth/token"
  }
}

Connector Config Parameters #

Create a Datasource #

Method 1: OAuth Authentication (Recommended) #

With the new architecture, datasources are automatically created during the OAuth flow. Users simply need to:

1. Configure the Connector: Set up OAuth credentials in the connector configuration
2. Click Connect: Users click the “Connect” button in the datasource creation interface
3. OAuth Authorization: Complete the OAuth authorization flow
4. Auto-creation: System automatically creates the datasource with OAuth tokens

No manual datasource creation required - the system handles everything automatically!

Method 2: User Access Token Authentication (Legacy) #

For users who prefer direct token authentication, datasources can still be created manually:

Feishu Datasource #

curl -H 'Content-Type: application/json' -XPOST "http://localhost:9000/datasource/" -d '{
  "name": "Feishu Cloud Documents",
  "type": "connector",
  "enabled": true,
  "connector": {
    "id": "feishu",
    "config": {
      "user_access_token": "u-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "document_types": ["doc", "sheet", "slides", "mindnote", "bitable", "file", "docx", "folder", "shortcut"]
    }
  },
  "sync": {
    "enabled": true,
    "interval": "30s"
  }
}'

Lark Datasource #

curl -H 'Content-Type: application/json' -XPOST "http://localhost:9000/datasource/" -d '{
  "name": "Lark Cloud Documents",
  "type": "connector",
  "enabled": true,
  "connector": {
    "id": "lark",
    "config": {
      "user_access_token": "u-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "document_types": ["doc", "sheet", "slides", "mindnote", "bitable", "file", "docx", "folder", "shortcut"]
    }
  },
  "sync": {
    "enabled": true,
    "interval": "30s"
  }
}'

Datasource Config Parameters #

Note: When using OAuth authentication, access_token, refresh_token, token_expiry, refresh_token_expiry, and profile fields are automatically filled during the OAuth flow.

Configuration Parameters #

Required Parameters #

OAuth Auto-filled Fields #

Sync Configuration #

Supported Document Types #

The Feishu/Lark connector supports the following cloud document types:

• doc: Feishu/Lark documents
• sheet: Feishu/Lark spreadsheets
• slides: Feishu/Lark presentations
• mindnote: Feishu/Lark mind notes
• bitable: Feishu/Lark multi-dimensional tables
• file: Regular files
• docx: Word documents
• folder: Folders (supports recursive search)
• shortcut: Shortcuts (directly use API returned URLs)

Directory Access #

The connector keeps Feishu’s native folder hierarchy and creates folder directory documents during traversal

Usage Instructions #

Method 1: OAuth Authentication (Recommended) #

Step 1: Create Feishu/Lark App #

1. Visit the corresponding open platform:
   • Feishu: Feishu Open Platform
   • Lark: Lark Open Platform
2. Create a new app, apply for the following permissions:
   • drive:drive - Cloud document access permission
   • space:document:retrieve - Knowledge base document retrieval permission
   • offline_access - Offline access permission
3. Record the app’s Client ID and Client Secret

Step 2: Configure Connector #

1. Go to Connector Management in the system interface
2. Edit the Feishu or Lark connector configuration
3. Configure the following fields:
   • client_id: Your app’s Client ID
   • client_secret: Your app’s Client Secret
   • document_types: List of document types to sync
   • auth_url, token_url, redirect_url: OAuth endpoints (pre-configured)
4. Save connector configuration

Step 3: Create Datasource (OAuth Flow) #

1. Go to Data Source Management and click “Add Data Source”
2. Select Feishu or Lark connector
3. Click the “Connect” button (no manual configuration needed)
4. System redirects to Feishu/Lark authorization page
5. User completes authorization
6. System automatically creates datasource with OAuth tokens and user profile information

Method 2: User Access Token #

Step 1: Obtain User Access Token #

1. Log in to corresponding open platform
2. Obtain user access token

Step 2: Create Datasource #

1. Create corresponding datasource in system management interface
2. Configure user_access_token and document_types
3. Save datasource configuration