Skip to main content

​
Overview

Genesis connects to Google Workspace through the Connections page (Config → Connections). Two authentication methods are supported: You can create multiple named connections (e.g. shared, finance, marketing) and select them by name from agent tools using the connection_name parameter.
The legacy standalone Google Workspace setup page has been removed. All Google Workspace configuration now happens through Config → Connections.
Use User OAuth for interactive or user-facing agent workflows, and Service Account for automation or shared-folder jobs. Genesis resolves the selected Google Workspace connection in the current user and agent context, so only agents that are allowed to use that connection can run Google Workspace actions.

​
Prerequisites

Before creating a connection, set up a Google Cloud project with the required APIs:

​
Step 1: Create or select a GCP project

  1. Go to console.cloud.google.com
  2. Create a new project (e.g. Genesis_Google_Integration) or select an existing one

​
Step 2: Enable Google APIs

In your GCP project, go to APIs & Services → Library and enable:
  • Google Drive API
  • Google Sheets API
  • Google Docs API
  • Google Slides API
  • Google Calendar API (if using calendar tools)
  • Gmail API (if an agent reads and sends mail from its own mailbox)
  • Google Chat API (if talking to Genesis agents from Google Chat)
User OAuth lets each user authorize Genesis to access their own Google Drive. This is the preferred method for interactive workflows.
1

Configure the OAuth consent screen

In your GCP project, go to Google Auth Platform → Branding / Audience (older consoles: APIs & Services → OAuth consent screen). Set the app name and support email. For Audience, choose Internal to allow everyone in your Google Workspace organization, or External. While an External app is in Testing, only the accounts listed under Test users can connect — add each person who will connect, or the consent screen refuses them. Testing apps also expire their refresh tokens after seven days, so publish the app for lasting connections.
2

Create the OAuth client

Go to Google Auth Platform → Clients → Create client (older consoles: APIs & Services → Credentials → Create Credentials → OAuth client ID) and select Web application. You add the redirect URI in a later step, once Genesis shows it. Note the Client ID and Client Secret.
3

Create a Google Workspace connection in Genesis

Go to Config → Connections and create a new Google Workspace connection. Select User OAuth as the auth type and enter the Client ID and Client Secret. Under More options, choose Access:Both also request openid and email. Once Access is set it decides the scopes, whatever the connection’s Scopes field holds. A connection saved before the Access option existed keeps its configured scopes until you edit and save it.Also under More options, Gmail and Calendar add their own scopes to whatever Access asks for. Both default to No access:Gmail and Calendar act as the Google account the person signed in to when they clicked Connect OAuth. Gmail works only with User OAuth; a service account has no mailbox of its own.
A User OAuth grant belongs to the Genesis user who connected. Each person who uses the tool works in the mailbox of their own grant, and someone without one is asked to connect. To give an agent one mailbox of its own that serves everyone, turn on the agent mailbox instead.
4

Add the redirect URI to the OAuth client

After saving, the Finish OAuth Setup panel shows the exact callback URL for this connection, for example https://<your-genesis-host>/api/connections/google_workspace/<connection-name>/oauth/callback/ui. The URL contains the connection name, so each connection needs its own entry. Copy it into the OAuth client’s Authorized redirect URIs in Google Cloud and save. A missing or different URI fails with redirect_uri_mismatch.
5

Connect OAuth

Click Connect OAuth and approve the permissions Google lists. Genesis asks Google for offline access, so it receives and stores a refresh token and renews the hour-long access token itself, including when Google rejects one early. If Google does not return a refresh token, the connection is not marked connected and Genesis tells you to remove the app at myaccount.google.com/permissions and connect again. In chat-driven workflows, the authorization request remains visible until resolved even if you switch to another thread.
6

Test

Click Test connection, or use google_drive(action="LIST"). With Gmail on, the test also reads the mailbox profile (users.getProfile); with Calendar on, it lists one calendar (calendarList.list). A failure there usually means the API is not enabled in the Google Cloud project, or the grant predates the option: enable the API and click Connect OAuth again. If the test reports that Google no longer accepts the connection’s sign-in, click Connect OAuth again; if that still fails, remove the app at myaccount.google.com/permissions and reconnect.

​
Changing Access later

To give an existing read-only connection write access, edit it, set Access to Read and write, save, then click Connect OAuth again so Google asks for the edit permissions. Until you reconnect, the stored grant stays read-only: a write such as creating a Sheet returns a message saying the connection was authorized read-only and how to fix it, rather than Google’s raw ACCESS_TOKEN_SCOPE_INSUFFICIENT error.

​
Sending mail from the agent’s mailbox

The gmail tool reads, searches, labels, archives and drafts directly. SEND and REPLY go through Action Review as the gmail.send.v1 action:
  • Mail whose recipients (To, Cc and Bcc) are all in the mailbox’s own domain is sent at once.
  • Mail with any other recipient waits for a person to approve it; approving it sends it, once. Without the agent mailbox, the approver needs their own grant on the connection, signed in to the same mailbox; an approval through another mailbox or no grant sends nothing. With it on, anyone with access to the agent may approve, with no grant of their own. An agent never approves. A mailbox on a consumer domain such as gmail.com has no internal recipients.
These are the shipped defaults (default-gmail-send-review-v1 and default-gmail-send-internal-v1); a tenant policy that writes its own rules for gmail.send.v1 replaces them. Mail content the tool returns is marked as untrusted external content, and each message body is fenced, so the agent treats it as data rather than instructions. GET_ATTACHMENT saves an attachment into the conversation’s uploads.

​
The agent mailbox

Normally a grant answers for the person calling the tool, so one sign-in as gennie@your-domain serves nobody else. Agent mailbox is an opt-in setting, off by default, that makes the connection’s grant belong to the connection, for the agents assigned to it: To turn it on for a connection named gennie_google:
1

Create the connection

Add a shared Google Workspace connection named gennie_google with User OAuth, Gmail set to read, label, draft and send, and Calendar as you need it.
2

Sign in once, as the mailbox

Click Connect OAuth and, in Google’s account chooser, pick gennie@your-domain. Your Genesis account is now the one that holds this sign-in, and the one people are told to ask when it needs reconnecting.
3

Assign the connection to the agent

Give the connection’s access to an RBAC role the agent holds, ideally a role only that agent has (Config → Connections, then the connection’s roles; assign the role to the agent in Roles). Roles shared with other agents assign the mailbox to those agents too. Naming the agent in the locator’s owner_bot_id or allowed_bot_ids also counts; * or an empty list assigns nobody.
4

Turn on the agent mailbox

As someone with the manage all connections permission, open the connection’s Connect OAuth panel and click Use as the agent mailbox. Or call the API:
Genesis reads the address from Gmail and pins it. {"signed_in_user_id": "..."} names another person’s sign-in; the default is yours. GET reads the setting, including who set it and when, and DELETE turns it off.
Things to know:
  • “Internal” is measured from the mailbox. The domain comes from the address Gmail reports, so with gennie@your-domain mail to your-domain is sent at once and anything else waits for review.
  • Changing the signed-in account asks again. If the person holding the sign-in reconnects and picks a different Google account, the agent refuses to use it until an admin turns the agent mailbox on again, which pins the new address. Reconnecting as the same account just works. Someone else clicking Connect OAuth on the connection only creates their own grant, which Drive and Sheets use for them and the Gmail and Calendar tools ignore.
  • Switching the connection away from User OAuth while the agent mailbox is on makes the Gmail and Calendar tools refuse until it is switched back or the setting is turned off. They never drop to per-person sign-ins.
  • An agent’s own turn with no person behind it, such as a scheduled task, may use the mailbox too, and its audit row names only the agent.
  • Every use is on the record. The audit log’s connection.agent_mailbox_used rows name the person acting (as the actor), the agent, the mailbox, the tool action and whether it was used or refused. In a turn, the person acting is whoever asked the agent. When a held send runs, it is whoever approved it. connection.agent_mailbox_set rows name who changed the setting. A sent mail’s Action Review row names who asked, who approved, and the mailbox it leaves from.
  • Mail stays untrusted. Nothing in a message can approve anything.
  • The token stays in the encrypted secret store, under the person who signed in, and never appears in logs, audit rows or tool results.

​
Option B: Service Account Setup

Service accounts are ideal for unattended automation, shared folders, and scheduled jobs.
1

Create a service account

In your GCP project, go to IAM & Admin → Service Accounts. Create a new service account (e.g. GenesisBot_ServiceAccount). Assign the Editor role (or Viewer for read-only).
2

Generate a JSON key

Click Actions (…) → Manage Keys → Add Key → Create New Key → JSON. Download and store the file securely.
This file grants API access. Store it securely and rotate keys periodically.
3

Share a Drive folder with the service account

Create a folder in Google Drive (e.g. Genesis_Shared_Folder). Share it with the service account email (e.g. [email protected]) with Editor access. Copy the folder ID from the URL.
4

Create a Google Workspace connection in Genesis

Go to Config → Connections and create a new Google Workspace connection. Select Service Account as the auth type. Paste the JSON key contents (or the individual fields: project ID, client email, private key, private key ID) and the shared folder ID.
5

Test

Use google_drive(action="TEST_CONNECTION") or google_drive(action="LIST") to verify. Use GET_SERVICE_ACCOUNT_EMAIL to confirm which account is active.

​
Google Chat direct messages

Genesis can receive direct messages from Google Chat and route them to an individual Genesis agent. Google Chat uses the same Google Workspace connection type, but the connection must be a shared Service Account connection that the agent can access. User OAuth connections are not used for Google Chat ingress. Add these optional fields to the shared Google Workspace connection:
1

Enable the Google Chat API

In the GCP project used by the service account, enable Google Chat API.
2

Create the shared connection

In Config → Connections, create or edit a Google Workspace connection with Shared connection scope and Service Account authentication. Enter the service-account credentials, then set google_chat_endpoint_audience to the bot-specific HTTPS event URL and google_chat_allowed_domain_id to your Workspace domain ID.
3

Configure the Google Chat app

Configure the Google Chat app to use an HTTP endpoint at the same bot-specific URL. Set its authentication audience to the exact value saved in google_chat_endpoint_audience.
4

Message the agent in a direct message

Open a 1:1 Google Chat direct message with the agent and send a message. Only direct messages from human users in the configured domain are accepted; spaces and other event types are ignored.
For the phase-gate behavior available to continuous Blueprint Missions, see Human approval gates in continuous missions. Send /new in the direct message to start a new Genesis DM episode. Follow-up messages stay correlated within the current episode; a new episode does not reuse the previous episode’s work correlation.

​
Context Graph scanning

Google Workspace connections can be registered as Context Graph lineage sources from Digital Twin and Context Graph. Saving a connection does not add it to the graph automatically — use Add source in the Twin configuration modal. Scheduled scans run headless and require a long-lived credential. User OAuth connections appear in the Twin picker but Add source stays disabled; use a Service Account connection for unattended Context Graph harvesting. When registered, Twin reads documents from the configured shared folder, clusters them into wiki summaries, and indexes content for semantic search.

​
Multiple Named Connections

You can create multiple Google Workspace connections for different teams or purposes:
When connection_name is omitted, Genesis resolves the effective default google_workspace connection for the current user (My default, then Role default). When multiple role defaults for google_workspace conflict, Genesis treats the scoped default as unset and can fall back to legacy service-account configuration instead of returning an error. See Default connection layers.

​
Migration from Legacy Setup

If you previously configured Google Workspace through the old standalone setup page, Genesis automatically runs the aa004_google_workspace_connection startup migration to copy those credentials into a google_workspace.shared connection. No manual action is required when the migration succeeds. The migration is idempotent. If google_workspace.shared already exists in AppConfig, Genesis skips it. On retry after a partial failure, Genesis reconciles secrets that were already created instead of aborting on a conflict. If the migration fails, Genesis logs a CRITICAL STARTUP MIGRATION CHAIN HALTED message listing every later startup migration that was blocked (for example LLM provider backfill migrations). Resolve the reported failure and restart Genesis; pending migrations run on the next startup. Search Pulse Monitoring Live Logs or your server log for STARTUP MIGRATION CHAIN HALTED.