Google Workspace Source

Connect Google Workspace as a source to analyze calendar activity, meeting load, and collaboration patterns in your warehouse. The connector uses a delegated Google Cloud service account to read directory users and the calendars permitted by your Workspace configuration.

For capabilities and use cases, see the Google Workspace connector overview. To run pipelines inside your Snowflake account, see Snowflake Native ETL.

Prerequisites

Before you begin, ensure you have:

• A Google Workspace domain and a Super Admin who can authorize domain-wide delegation
• A Google Cloud project you can administer, or permission to create one
• Permission to enable APIs and create a service account and JSON key in that project
• The email address of a Workspace administrator who can list directory users

Google documents the service-account and domain-wide delegation flow in Using OAuth 2.0 for Server to Server Applications.

Supported Objects

Object	Sync Mode	Description
Users	Full Refresh	Directory profiles, account status, and organizational-unit assignments
User Calendars	Full Refresh	Calendar memberships and access context for Workspace users
Calendar Event Series	Incremental	Recurring event definitions and schedules
Calendar Event Occurrences	Incremental	One-off events and expanded recurring instances with timing, organizer, attendee, location, conference, and visibility data

Not Yet Supported

• Room and resource calendars, their events, and Workspace resource inventory
• Calendar access-control lists and user calendar settings
• Creating, updating, or deleting Google Workspace data

Incremental Sync

Calendar event series and occurrences use Google Calendar sync tokens to fetch changes after the initial read. Supaflow expands recurring events into individual occurrences, so each meeting instance can be analyzed separately while the recurring series remains available as its own object.

Initial Calendar History sets the historical backfill boundary when a calendar is first added. It is not a rolling retention limit: previously loaded history is not aged out. Future Calendar Window controls how far ahead one-off events and recurring occurrences are materialized, and the frontier advances on later syncs.

Users and user-calendar memberships use full refresh because these objects provide the current directory and calendar-access snapshot. They are fully re-read on every pipeline execution in which they are selected. The pipeline's manual or scheduled execution frequency determines how often this occurs; there is no separate connector-level or per-object full-refresh schedule. Schema Refresh Interval controls schema metadata refresh, not data-sync frequency.

Google may invalidate a calendar sync token after changes such as calendar access updates; when that happens, Supaflow automatically performs a clean resync for the affected event object.

How Google Calendar Behavior Affects the Data

Directory users and calendar memberships are snapshots

Google's Directory users list returns the current user directory, while each user's CalendarList describes that user's calendar memberships and effective access. Supaflow refreshes both as current snapshots.

A shared calendar can appear in several users' calendar lists. User Calendars retains each user-to-calendar relationship, but Supaflow reads the events once per unique calendar ID to avoid duplicating the same shared calendar's events.

Recurring series and occurrences are separate API views

Google represents recurring definitions separately from their expanded instances. Supaflow therefore exposes both views: Calendar Event Series preserves each recurrence definition, while Calendar Event Occurrences provides one row for each one-off event or expanded recurring instance. See Google's recurring-event behavior.

Occurrence rows include the parent series identifier and original scheduled time so rescheduled or cancelled instances can still be associated with the correct series.

Occurrence windows are backfill and expansion boundaries

Recurring schedules can continue without an end date, so Supaflow applies Initial Calendar History when a calendar is first added and materializes calendar activity through the Future Calendar Window. On later runs, Supaflow reads the newly opened future interval for the whole calendar. This captures future one-off events and recurring instances even when the original event or series has not changed.

Previously loaded occurrence history is retained, while the series object keeps the recurrence definition.

Cancelled instances and deleted events are different

Google uses a cancelled status for both skipped recurring instances and deleted events. Supaflow preserves that distinction so cancelling one instance does not remove the active recurring series.

Google returns limited detail for some cancellation and deletion records, so descriptive fields can be empty on those rows. See Google's event status documentation.

Calendar permissions determine visible event detail

Domain-wide delegation does not bypass Calendar permissions. Google can hide private-event details from a user with reader access while exposing them to users with stronger access. Supaflow uses the strongest available readable membership for each unique calendar, but fields can still be limited when no included user can view the details. See Google's Calendar access-role definitions.

Google can require a clean event resync

Google can invalidate incremental state after it expires or calendar access changes. Supaflow performs the required clean event resync automatically, so an incremental run can occasionally take longer and process a larger batch even when few events were edited. See Google's incremental synchronization guide.

Authentication

The connector authenticates with a Google Cloud service-account JSON key and impersonates the configured Workspace Admin Email through domain-wide delegation. It is read-only.

Google Cloud IAM roles do not grant access to Workspace users or calendars. A Workspace Super Admin must separately authorize the service account's numeric OAuth client ID for the required scopes in the Google Admin console. Follow the complete setup below.

Google Cloud and Workspace Setup

Complete this setup once for each service account. You can reuse an existing project or service account that meets the same requirements. Follow Google's service-account credential guide and domain-wide delegation guide for the current console workflow.

1. Enable the required APIs

In the Google Cloud project that owns the service account, enable:

• Admin SDK API
• Google Calendar API

See Google's API enablement guide if you need help or do not have permission to enable them.

2. Create a service account and JSON key

Create or reuse a service account, then create a JSON key for it. The connector does not require a Google Cloud project role for Workspace access; Workspace access comes from the read-only domain-wide delegation grant and the permissions of the users it impersonates.

If key creation is restricted by organization policy, ask your Cloud administrator to approve a service-account key. See Google's service-account key guide for current requirements.

Key Security

The JSON key file contains a private key. Store it securely and never commit it to version control. Supaflow encrypts the uploaded credential at rest. Rotate the key according to your organization's credential policy.

3. Authorize the required Workspace scopes

A Workspace Super Admin must authorize the service account's numeric OAuth client ID for domain-wide delegation. Use the numeric client ID shown for the service account or in the JSON key's client_id value. Do not use the service account email address or private-key ID.

Authorize these comma-delimited scopes:

https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/calendar.calendarlist.readonly

The scopes provide the following read-only access:

Scope	Used For
admin.directory.user.readonly	Discovering Workspace users and organizational-unit membership
calendar.events.readonly	Reading one-off events, recurring series, and expanded occurrences
calendar.calendarlist.readonly	Discovering primary, selected, and shared calendars for included users

Authorizing all three scopes supports the default PRIMARY_AND_SELECTED mode and ALL_READABLE. If the source will always use PRIMARY_ONLY, you may omit calendar.calendarlist.readonly; add it before changing to either broader mode. See Google's domain-wide delegation instructions and Calendar API scopes.

Google says delegation changes usually take effect within a few minutes but can take up to 24 hours to propagate.

4. Configure and test the Supaflow source

1. Create a Google Workspace source in Supaflow
2. Set Workspace Admin Email to an active user in the Workspace domain who can list directory users
3. Keep Workspace Customer ID as my_customer unless your administrator provides a specific Directory customer ID
4. Upload the downloaded JSON file under Service Account Key File
5. Choose the calendar and user scope described in Configuration
6. Click Test & Save

Supaflow verifies delegated authentication, Directory access, and the calendar permission required by the selected calendar scope. A successful test is also the simplest way to confirm that the Admin console grant has propagated.

Configuration

In Supaflow, create a new Google Workspace source with these settings.

Authentication

Workspace Admin Email*

The Workspace administrator the service account impersonates for directory discovery.

Workspace Customer ID

The Directory API customer ID. Keep the default my_customer to use the customer associated with the administrator.

Service Account Key File*

Upload the service-account JSON key configured for Workspace domain-wide delegation.

Sync Settings

Calendar Scope

Choose which calendars to read:

• PRIMARY_ONLY reads each included user's primary calendar
• PRIMARY_AND_SELECTED reads primary calendars and calendars selected in users' calendar lists (default)
• ALL_READABLE reads every non-virtual, non-resource calendar visible to the included users

Included User Emails

Optional comma- or newline-separated allowlist. Leave blank to include every user matched by the organizational-unit filter.

Included Organizational Units

Optional comma- or newline-separated organizational-unit paths. Descendant units are included.

Sync Suspended User Calendars

Allow suspended or archived users to contribute calendars. Their directory rows remain available when this option is off.
Default: disabled

Include Virtual Calendars

Include generated holiday, birthday, and contacts calendars.
Default: disabled

Initial Calendar History

Number of historical days to read when a calendar is first added. Previously loaded history is retained.
Default: 180; range: 1–3650

Future Calendar Window

Number of future days for which one-off events and recurring occurrences are materialized.
Default: 365; range: 1–3650

Advanced Settings

Schema Refresh Interval

Schema refresh interval in minutes. Use 0 to refresh before every pipeline run, -1 to disable automatic refresh, or a positive value for a scheduled interval.
Default: 60

Click Test & Save. Supaflow verifies the delegated credentials, directory access, and the calendar permissions required by the selected scope mode. After schema discovery, select the objects and fields you want to include in the pipeline.

Rate Limiting

Google applies API quotas to Calendar API requests. Supaflow retries transient rate-limit and server errors with backoff. Large domains or broad calendar scope can take longer to sync; if necessary, narrow the included users or organizational units and schedule large runs during off-peak periods. See Google's Calendar API quota documentation for current limits.

Troubleshooting

unauthorized_client: Client is unauthorized to retrieve access tokens

The service account is not authorized for one or more requested domain-wide delegation scopes.

1. Confirm the JSON key belongs to the service account whose numeric OAuth client ID was authorized in the Google Admin console; do not authorize the service account email or private-key ID
2. Confirm the configured scopes exactly match the scopes listed in Authorize the required Workspace scopes
3. If Calendar Scope is PRIMARY_AND_SELECTED or ALL_READABLE, confirm the calendar-list read-only scope is present
4. Wait for a new Admin console grant to propagate, then test again; Google says propagation can take up to 24 hours

No users are discovered

1. Confirm Workspace Admin Email belongs to the same Workspace customer and can list directory users
2. Keep Workspace Customer ID as my_customer unless you intentionally use a specific customer ID
3. Check Included User Emails and Included Organizational Units for filters that exclude every user

A shared calendar is missing

1. Use PRIMARY_AND_SELECTED for selected shared calendars or ALL_READABLE for all non-resource readable calendars
2. Confirm at least one included user can read the calendar
3. Confirm the service account is authorized for the calendar-list read-only scope
4. Enable Include Virtual Calendars only when you also need generated holiday, birthday, or contacts calendars
5. Room and resource calendars are not supported

Expected occurrences are missing

1. Confirm the relevant calendar and event objects are selected in the pipeline
2. Check that Initial Calendar History and Future Calendar Window cover the dates you expect
3. Confirm the delegated user has permission to see the event details; private events may expose limited fields
4. Review the Job Details page for the specific object failure

---

Related Pages

• Google Workspace connector overview
• Create an ingestion pipeline
• Snowflake destination
• Google Analytics 4 source
• Google Ads source
• Google Drive source

---

Support

Need help? Contact us at support@supa-flow.io