> 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/connectors/google-drive.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.