> 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. # Gmail Service Account > Configure a Google Workspace Service Account with Domain-Wide Delegation for organization-managed Gmail indexing. Use a Service Account when a Google Workspace organization centrally approves mailbox indexing. A Workspace administrator configures Domain-Wide Delegation, and an OpenCore Admin uploads the key and provides the Primary Admin Email. ## Prerequisites Use Standard mode. You need a Google Cloud Project controlled by the organization, the Gmail API and Admin SDK API enabled in that project, a Google Workspace administrator who can configure Domain-Wide Delegation, and an approved administrator or owner account in the Workspace organization. ## Create the Service Account Create a Service Account in Google Cloud, enable Domain-Wide Delegation for it, and create a JSON key. OpenCore requires a JSON object whose `type` is `service_account`. ```json { "type": "service_account", "project_id": "", "private_key_id": "", "private_key": "", "client_email": "", "client_id": "", "token_uri": "https://oauth2.googleapis.com/token" } ``` Keep the key secret. Record the Service Account OAuth client ID separately; the Workspace delegation entry uses this numeric client ID, not the Service Account email. ## Configure Domain-Wide Delegation In the Google Workspace Admin console, add the Service Account OAuth client ID to Domain-Wide Delegation and authorize exactly the scopes required by the current Gmail connector: | Scope | Current use | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `https://www.googleapis.com/auth/gmail.readonly` | Impersonate every Workspace user returned by the Admin SDK to list threads and read messages. | | `https://www.googleapis.com/auth/admin.directory.user.readonly` | Impersonate the Primary Admin Email to list user email addresses in the Workspace domain. | | `https://www.googleapis.com/auth/admin.directory.group.readonly` | Supply read-only group-directory authorization required by the Google credential contract; Gmail thread access records do not receive group IDs. | Do not copy Google Drive scopes into this delegation. The Gmail connector does not request Drive content or metadata access. ## Add the credential to OpenCore 1. Sign in to OpenCore as an Admin and open **Documents & Knowledge**. 2. Select **Gmail**, choose **Service account**, and upload or paste the Service Account JSON key. 3. Enter the **Primary Admin Email** for an administrator or owner in the Google organization that owns the Gmail accounts approved for indexing. 4. Create the credential, confirm it appears in the credential list, and select it when creating the Gmail connector. The Primary Admin Email is used for Admin SDK directory access. After the connector lists Workspace users, the Service Account impersonates each returned user when it reads that user's Gmail threads. ## Account coverage and permission sync With working Domain-Wide Delegation and directory permissions, the connector processes the user addresses returned for the Primary Admin Email's Workspace domain. A 403 or 404 from the directory list causes the implementation to fall back to the configured Primary Admin Email, so confirm account coverage from the actual index result. Every indexed thread is non-public and carries the mailbox used to fetch it as its only external user access. Message recipients and Workspace groups are not added to that access entry. When Gmail permission synchronization runs, it refreshes this same mailbox-only record for threads returned in its time window. ## Verify updates Create a Gmail connector with an approved indexing start date and a representative mailbox boundary. The default refresh frequency is 30 minutes and can be changed to another value of at least one minute. Run the first index attempt and verify the expected accounts, threads, and plain-text content before attaching the document set to an Agent. Creating another Service Account or OAuth credential preserves the existing Gmail credentials. Keep separate credentials for separate Workspace organizations or approval boundaries, and check the selected credential before running an index attempt. ## Troubleshooting | Symptom | Check and correct | | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | JSON type is rejected | Upload a valid key whose `type` is `service_account`, not a Web OAuth client JSON. | | Cannot impersonate a user | Confirm Domain-Wide Delegation is enabled for the Service Account and uses its OAuth client ID. Verify that the user still exists and has Gmail enabled. | | Directory or missing-scope error | Authorize all three Gmail connector scopes in the Workspace delegation entry and verify that the Primary Admin Email can list users. | | Only the Primary Admin Email is indexed | The directory user list returned 403 or 404. Correct Admin SDK access and delegation, then run a new index attempt. | | A user's mailbox is skipped | The connector skips a mailbox when Gmail reports that mail service is not enabled for that user. Confirm the account has a provisioned Gmail mailbox. | ## Related pages * [Gmail Overview](/opencore/knowledge/gmail/overview) explains indexed content, account coverage, updates, and permission boundaries. * [Gmail OAuth](/opencore/knowledge/gmail/oauth) covers browser-based authorization with an uploaded OAuth app JSON. * [Connectors & Indexing](/opencore/knowledge/connectors) explains document sets and index attempts.