> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/google-drive.md). # Google Drive K-AI ingests files from Google Drive via the Drive v3 API. The connector authenticates as a service account, traverses either the entire shared drive estate visible to that account or a designated folder, and syncs incrementally using the Drive Changes API. Drive's native permission model (per-file collaborators, shared drive members) is preserved as ACLs. ## Supported source versions Latest API only — Google Drive v3 (`https://www.googleapis.com/drive/v3/`). The API is versionless from a deployment standpoint; new fields appear without breaking changes. ## Authentication Authentication uses a **Google Cloud service account** with a JSON key. The service account must be granted access to the target Drive content via one of: * **Domain-wide delegation** (Google Workspace admin) — the service account impersonates a workspace user and inherits its Drive permissions. * **Direct share** — the target folder or shared drive is explicitly shared with the service account email (`@.iam.gserviceaccount.com`). The connector requests the following scopes: * `https://www.googleapis.com/auth/drive` * `https://www.googleapis.com/auth/drive.readonly` * `https://www.googleapis.com/auth/drive.metadata.readonly` * `https://www.googleapis.com/auth/drive.file` * `https://www.googleapis.com/auth/drive.appdata` * `https://www.googleapis.com/auth/drive.metadata` * `https://www.googleapis.com/auth/drive.photos.readonly` ## Configuration | Field | Type | Required | Description | | ---------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `sa_description` | object (JSON) | yes | Full JSON content of the service account key file. Encrypted at rest by the platform. | | `folder_name` | string | no | Restrict ingestion to a specific folder visible to the service account. When unset, every drive item the service account can list is ingested. | `supportsAllDrives=true` and `includeItemsFromAllDrives=true` are set on every list call, so shared drives are included alongside My Drive. ## Document types ingested * Native Google Workspace files — **Docs**, **Sheets**, **Slides**, exported on the fly to DOCX / XLSX / PPTX. * Office files — DOCX, XLSX, PPTX. * PDF. * Plain text and Markdown. * Images — JPG, PNG, GIF, WebP. OCR runs in the [indexation pipeline](/knowledge-ai/sources-and-ingestion/indexation-pipeline.md). * Other binary attachments — routed through the appropriate MIME-based extractor. Google **Forms** and **Sites** are not ingested. ## Sync mode Incremental sync uses the **Drive Changes API** (`changes.list?pageToken=...`). After an initial full listing (`files.list`), the connector calls `changes.getStartPageToken` once and persists it. Subsequent syncs request only the changes since the token; the response contains both upserts and deletions, so removals propagate immediately to the K-AI Instance. Tokens are durable for 30 days. If a token expires, the connector falls back to a full re-listing and emits a fresh token. ## ACL handling Each file's permissions are read from `permissions` on the Drive item (eagerly expanded with `fields=permissions(type,emailAddress,role,domain)`). Three permission types are mapped: * **`user`** — individual collaborator email. * **`group`** — Google Group email (resolved to its member set via the Admin SDK if domain-wide delegation is configured). * **`domain`** — the entire workspace domain (e.g. `acme.com`). Anyone-with-the-link sharing is mirrored as a public ACL inside the K-AI Instance and flagged in the document metadata. Shared drive membership is captured as a group grant — every member of the shared drive inherits read access to every file inside. [K-AI MCP](/knowledge-ai/k-ai-mcp/mcp.md) replays the ACL at retrieval time. A user who lost Drive access between syncs will stop seeing the document at the next sync cycle. ## Rate limits & throttling The Drive API enforces per-project quotas (default: 12,000 requests / minute) and per-user quotas (1,000 requests / 100s). The connector caps concurrency to stay within the per-user budget and applies exponential back-off on `403 userRateLimitExceeded` and `429` responses. ## Known limitations * **Native Google file exports** are subject to the Drive API's export size cap (10 MB for Docs, 100 MB for Sheets). Larger files are flagged in the document metadata and skipped. * **Shared drives** require the service account to be a member; service accounts cannot enumerate shared drives they have not been added to. * **Encrypted files** (CSE — Client-Side Encryption) cannot be decrypted by the service account and are skipped. * **Trash** is excluded by default (`trashed=false`). Restored files reappear on the next sync via the Changes API. * **Comments and suggestions** on Google Docs are not ingested as separate entities; they are flattened away by the export. ## Setup walkthrough 1. **Create a Google Cloud project** and enable the **Google Drive API**. 2. **Create a service account** in IAM & Admin → Service Accounts. Generate a JSON key and download it. 3. **Grant the service account access** to the target Drive content. Either: (a) share the folder / shared drive with the service account email, or (b) configure domain-wide delegation in the Google Workspace admin console and add the scopes listed above. 4. **Add the source in the K-AI admin portal**: select Google Drive, paste the JSON key content into `sa_description`, optionally set `folder_name`. Set the sync schedule (default: every 15 minutes). 5. **Trigger a test sync** and confirm the document count via the [Documents endpoint](/knowledge-ai/sources-and-ingestion/instance-api/documents.md) of the K-AI Instance.