Skip to content
Docs menu

Google accounts

Connect as many Gmail and Google Workspace accounts as you like, pick which calendars block time, keep busy time fresh within a minute, bring your own OAuth client, and see exactly what Venom reads and stores.

View .md

Connect your personal Gmail, your company's Workspace and a client's Workspace, one after another. Each connection lists its calendars, and you choose which of them block time. Busy time from all of them stays fresh within about a minute, and Venom can write a booking into any calendar you can edit, with a Google Meet link.

Nothing contacts Google until you connect an account.

Connecting an account

In the Calendar app, choose Connect Google. Google asks you to sign in and to allow Venom to:

  • see and edit events on your calendars (calendar.events), and
  • see the list of your calendars (calendar.calendarlist.readonly).

Venom also asks for your email address (openid email), which names the account in the app. When you come back, Venom lists the account's calendars, primary first, and starts syncing.

Connect another account the same way, as many times as you like: Google always shows its account picker, so you can pick a second account while signed in to the first. Connecting an account you already connected replaces its sign-in rather than adding it twice. People → Settings has the same Connect Google calendar button, and brings you back there.

The app's button opens GET /api/workspace/calendar/google/connect. Google sends you back to GET /api/workspace/calendar/google/callback. The sign-in link is good for 10 minutes and works once, only for the member who started it.

Busy-only connections

For an account Venom should never write to, such as a client's Workspace where you only want your meetings to block time, choose Connect for busy time only (/api/workspace/calendar/google/connect?mode=busy). Google then asks only for free/busy access (calendar.events.freebusy) and the calendar list. Venom sees when you are busy, but no titles or details, and it can't book into that account. It refreshes by polling, since Google sends no change notifications without event access.

Choosing which calendars block time

Each calendar has four switches, in the app or through PATCH /api/workspace/calendar/calendars/{id}:

Switch Default What it does
Blocks time (check_conflicts) on for calendars you own, off for shared and subscribed ones such as holidays its busy time hides slots on your booking pages
Tentative counts as busy (tentative_busy) on events you answered "maybe" to block time
All-day counts as busy (allday_busy) off all-day events block the whole day (most are reminders, not time away)
Receives invites (receive_invites) off gets an email invite for bookings written to another calendar, so this one shows them as busy

Events marked Free in Google, events you declined and cancelled events never block time. Neither do the events Venom wrote for your own bookings, which already count once.

GET /api/workspace/calendar/accounts lists your accounts with their calendars, and DELETE /api/workspace/calendar/accounts/{id} disconnects one.

How busy time stays fresh

  • Change notifications. When your Venom Cloud has a public https address, Venom asks Google to notify it of changes to each calendar that blocks time, and of calendars added to or removed from the account. A change shows up on your booking pages within seconds. Several changes inside 10 seconds are fetched together.
  • Polling. Every account is also checked every 5 minutes, or every 2 minutes when Google hasn't sent a notification in the last day. A self-hosted Venom without a public address lives on polling alone.
  • Just in time. Opening a booking page checks again (at most once a minute per account), and so does confirming a booking, every time.

Google's notifications last a week. Venom renews each one a day before it ends. If Google's rate limit is reached, Venom waits and tries again, and shows the delay on the account.

When an account needs you

If you revoke Venom's access in your Google account settings, or Google ends the sign-in, the account shows Reconnect this account and Venom stops syncing it until you connect it again. Its calendars keep their settings.

Disconnecting an account in the app revokes Venom's access at Google, stops its notifications, and deletes its calendars and their cached busy time.

Bringing your own OAuth client

Venom Cloud connects through the operator's Google OAuth client, set as GOOGLE_CALENDAR_CLIENT_ID and GOOGLE_CALENDAR_CLIENT_SECRET. An organisation can use its own client instead: Calendar settings, Google OAuth client (owners and admins; PUT /api/workspace/calendar/google/client). The secret is sealed in the org's vault and never shown again. Self-hosters without the deployment variables must do this before anyone can connect.

  1. In the Google Cloud console, create a project (or pick one) and enable the Google Calendar API.
  2. Under Google Auth Platform, set up the consent screen (Branding, Audience) and add the scopes .../auth/calendar.events, .../auth/calendar.calendarlist.readonly and .../auth/calendar.events.freebusy (the last one may need typing in by hand).
  3. Under Clients, create an OAuth client of type Web application and add the redirect URI that Calendar settings shows, which is https://<your cloud host>/api/workspace/calendar/google/callback.
  4. Paste the client ID and secret into Calendar settings.

Pick the audience on the consent screen:

Audience Who can connect Google review Trade-offs
Internal accounts in your own Google Workspace only none the simplest choice for a company; personal Gmail and other companies' accounts can't connect
External, Testing up to 100 Google accounts you list as test users none Google ends Testing-mode sign-ins after about 7 days, so each account has to reconnect weekly
External, In production anyone needed for these sensitive scopes (brand check, a demo video, a few days to weeks) no weekly reconnects; what a hosted Venom Cloud uses

Removing the org's client (DELETE /api/workspace/calendar/google/client) falls back to the deployment's. Accounts connected through the old client must reconnect.

What Venom reads and stores

What Where it is kept
Your email address, from Google's sign-in the account row, to name it
The sign-in tokens sealed in the org's vault (AES-256-GCM, bound to the account); never shown, logged or put in the audit log
The calendar list: names, colours, time zones, whether you can edit each one row per calendar, with your switches
Busy blocks of the calendars that block time, from a day ago to 120 days ahead: start, end, all-day, tentative the busy-time cache
Event titles (not for busy-only connections) the busy-time cache, shown only in your own week view; never on a booking page
Google's sync tokens and notification channels (each channel's secret only as a hash) per calendar

Venom doesn't read descriptions or attachments of your events, and doesn't keep events past the 120-day window. Attendees and locations come in the same answer: for the next days' meetings (not for busy-only connections), Venom People keeps the people they matched, a count of the rest, and the location text. Once a meeting has ended, an attendee who matched nobody waits in your own People review list (email and the display name Google gave) until you decide; one that ended after the sync last saw it is read once more by its id. Import past meetings in People settings reads the last 24 months with the same events.list and the same permission, only when you press it (see People meetings). Disconnecting deletes all of it.

Writing bookings

When a booking lands in a Google calendar, Venom inserts the event with your invitee as an attendee and, for a Meet location, asks Google for a Meet link. Google doesn't send its own invitation emails (sendUpdates=none); Venom sends its own invite. A reschedule moves the same event and keeps its Meet link, and a cancellation deletes it.

Agents

On the workspace MCP server (/workspace/mcp/calendar), agents use:

Tool What it does
calendar_account_list the member's accounts, their status and calendars
calendar_calendar_list every calendar with its switches
calendar_calendar_update change a calendar's switches, colour or time zone
calendar_account_remove disconnect an account

Reading needs calendar:read and changes need calendar:write on an OAuth grant, or the member's own API key (a team key is refused, since a calendar belongs to one member). Connecting an account needs Google's consent screen in a browser, so there is no tool for it.

For operators

Variable What it does
GOOGLE_CALENDAR_CLIENT_ID, GOOGLE_CALENDAR_CLIENT_SECRET the deployment's Google OAuth client. Without them (and without an org's own client), the Connect button explains what to set
VENOM_VAULT_KEYS required: tokens and org clients are sealed with it
VENOM_CLOUD_ORIGIN the public origin used for the redirect URI and the notification address; notifications need https
GOOGLE_OAUTH_BASE, GOOGLE_API_BASE tests only: point Venom at a fake Google (https, or http on loopback). Ignored on a production deploy

Google calls POST /api/integrations/calendar/google/notify without a session. Each notification carries the channel's secret token, which Venom checks against its stored hash. The sweep cron runs the polling and renewals.