> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Google Drive Service Account

> Configure a Google Workspace service account and Domain-Wide Delegation for organization-managed Google Drive indexing.

Use this method when your organization manages Google Workspace access through a service identity. A Workspace administrator approves the delegation and scope, and an OpenCore Admin uploads and maintains the credential and selects or associates it when configuring the connector.

## Prerequisites

Use Standard mode, because connectors and document indexing require it. You need a Google Cloud Project controlled by the organization, a Google Workspace administrator who can configure Domain-Wide Delegation, and the Primary Admin Email for the Workspace organization that owns the Drive content.

## Create the Service Account

In the Google Cloud Project, create a Service Account and create a JSON Key for it. Keep the key secret and upload it only through the protected OpenCore Admin screen.

```json
{
  "type": "service_account",
  "project_id": "<google-cloud-project-id>",
  "client_email": "<service-account>@<project-id>.iam.gserviceaccount.com",
  "private_key": "<keep-this-secret-and-upload-it-only-in-the-admin-panel>"
}
```

Record the Service Account OAuth client ID from Google Cloud. Domain-Wide Delegation uses that OAuth client ID, not the service account email address.

## Configure Domain-Wide Delegation

In the Google Workspace Admin console, add the Service Account OAuth client ID to Domain-Wide Delegation and authorize only the scopes currently required by the Google Drive connector:

| Minimum scope                                                    | Why OpenCore requests it                                          |
| ---------------------------------------------------------------- | ----------------------------------------------------------------- |
| `https://www.googleapis.com/auth/drive.readonly`                 | Read approved Google Drive content.                               |
| `https://www.googleapis.com/auth/drive.metadata.readonly`        | Read Google Drive metadata used to discover and identify content. |
| `https://www.googleapis.com/auth/admin.directory.group.readonly` | Read Workspace group membership for permission synchronization.   |
| `https://www.googleapis.com/auth/admin.directory.user.readonly`  | Read Workspace users for permission synchronization.              |

Do not add broader scopes unless the deployed connector changes its documented requirements. The Service Account impersonates the configured Primary Admin Email when it accesses Google Workspace.

## Add the credential to OpenCore

1. Sign in to OpenCore as an Admin and open **Documents & Knowledge**.
2. Select **Google Drive**, choose **Service account**, and upload the JSON Key.
3. Enter the **Primary Admin Email** for an administrator or owner of the Google Workspace organization that owns the Drive content.
4. Create the credential, then keep the key out of source control, Agent instructions, and shared documents.

Only Admins can upload, replace, or otherwise maintain the Service Account credential. The Admin also selects or associates that Google credential when configuring the connector; do not assume it is shared with other roles.

## Configure indexing scope

Choose the narrowest approved scope when the Admin configures the connector.

| Area     | Available options                                                                                                                 |
| -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| General  | **Include Everyone's My Drive** and **Include shared drives**.                                                                    |
| Specific | Comma-separated lists of **Shared Drive URLs**, **Folder URLs**, and **My Drive Emails**. Indexed folders include all subfolders. |
| Advanced | **Specific User Emails**, which indexes only files accessible to those users, and optional **Hide domain link-only files**.       |

The selected scope and the impersonated account's Google Drive permissions both limit what the connector can read. Domain-Wide Delegation does not replace content-owner approval for indexing.

## Verify the connector

Create a connector with one small, representative approved scope and run an index attempt. Review the attempt result, indexed document set, and any reported skipped files or errors before attaching the document set to an Agent or broadening the scope.

## Troubleshooting

| Symptom                   | Check and correct                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| JSON type is rejected     | Upload a valid JSON Key whose `type` is `service_account`, not an OAuth Client JSON.                                        |
| Primary Admin Email fails | Enter an existing administrator or owner email for the Google Workspace organization that owns the selected content.        |
| Delegation or Scope error | Confirm Domain-Wide Delegation uses the Service Account OAuth client ID and authorizes all four required scopes.            |
| 403 from Google Workspace | Verify that the Primary Admin Email has directory access and that Domain-Wide Delegation is active for the Service Account. |

## Related pages

* [Google Drive Overview](/opencore/knowledge/google-drive/overview) compares authentication methods and indexing scopes.
* [Google Drive OAuth](/opencore/knowledge/google-drive/oauth) covers browser-based authorization with an OAuth App.
* [Connectors & Indexing](/opencore/knowledge/connectors) explains document sets and index attempts.