Flowly
Log inDownload
Docs/Integrations/Google Workspace
Integrations

Google Workspace

Native tools for Google Calendar, Contacts, Drive, and Tasks (plus Gmail via the email tool) that call the Google REST APIs directly using an OAuth 2.0 access token.

This page covers the four Workspace data tools, how they are enabled, where their credentials live, and the honest state of the setup flow.

Tools

ToolPurposeActionsKey params
google_calendarList/manage calendar eventslist, get, create, update, delete, searchevent_id, summary, description, start, end, location, attendees, query, max_results, calendar_id
google_contactsRead-only contact lookupsearch, listquery, max_results
google_driveBrowse/read/create Drive fileslist, search, read, info, createfile_id, query, name, content, mime_type, max_results
google_tasksManage task lists and taskslists, tasks, create, complete, deletetasklist_id, task_id, title, notes, due, max_results

Notes:

  • google_calendar start/end are ISO 8601 datetimes (e.g. 2026-04-10T14:00:00+03:00). attendees is a comma-separated list of email addresses. calendar_id defaults to primary.
  • google_drive query uses Drive search syntax. For create, mime_type defaults to text/plain; use application/vnd.google-apps.document to create a Google Doc.
  • google_tasks tasklist_id defaults to @default. due is an ISO 8601 date.
  • google_contacts is read-only (search/list only).

API base URLs used: Calendar API v3, People API (contacts), Drive API v3, Tasks API v1.

Enabling the tools

The four Workspace tools (and the Gmail

email tool) register together, gated on the email channel being enabled β€” not on the integrations.googleWorkspace card.

{
  "channels": {
    "email": { "enabled": true }
  }
}

When channels.email.enabled is true, Flowly registers email, google_calendar, google_contacts, google_drive, and google_tasks at agent boot. Enabling the integrations.googleWorkspace card alone does not register these native tools.

The integrations.googleWorkspace block is a separate, display/opt-in toggle:

{
  "integrations": {
    "googleWorkspace": {
      "enabled": false,
      "email": ""
    }
  }
}

email here is display-only (the connected Google account address); enabled flags the integration card. Neither field controls native-tool registration.

Credentials

The native tools authenticate with an OAuth 2.0 access token obtained via a refresh-token grant. The credentials file is read from:

~/.flowly/credentials/gmail.json

It contains refresh_token, client_id, and client_secret. Flowly exchanges the refresh token at https://oauth2.googleapis.com/token for a short-lived access token and sends Authorization: Bearer <token> on every API call. The same token is shared across Gmail, Calendar, Contacts, Drive, and Tasks.

Warning

Unverified: The exact command/flow that writes gmail.json (including the requested OAuth scopes and the OAuth client configuration) is not present in this repository. The file appears to be produced by an external web/gateway OAuth flow (e.g. Flowly Cloud). If you do not have a gmail.json, obtain one through your Flowly Cloud account or the gateway's Google connect flow. The precise scope strings are not documented here because they are not defined in code we can cite β€” do not assume a specific scope set.

flowly setup google-workspace

A separate setup wizard exists:

flowly setup google-workspace

This wizard installs and authenticates the Google Workspace CLI (gws):

  1. Installs gws via npm install -g @googleworkspace/cli (Node.js required).
  2. Installs the gcloud CLI (Homebrew on macOS, apt on Linux) if missing.
  3. Runs gws auth setup then gws auth login.
  4. On success, sets integrations.googleWorkspace.enabled = true, records the detected account email, enables the exec tool, and allowlists the gws binary so the agent can run gws * commands without per-command approval.
This wizard wires up the

gws command-line path (driven through the exec tool), which is distinct from the native google_calendar/google_drive/google_contacts/google_tasks tools. The native tools still require channels.email.enabled and a valid ~/.flowly/credentials/gmail.json. Both paths can coexist.