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.
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.
- In the Google Cloud console, create a project (or pick one) and enable the Google Calendar API.
- Under Google Auth Platform, set up the consent screen (Branding, Audience) and add the scopes
.../auth/calendar.events,.../auth/calendar.calendarlist.readonlyand.../auth/calendar.events.freebusy(the last one may need typing in by hand). - 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. - 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.