Skip to content

Connect a Google Calendar

This guide shows you how to connect Google Calendar to a workspace. It’s per-workspace and per-member: it syncs your events for that workspace into Control Center, where you can also answer invitations, book, move and delete events. See Calendar and scheduling for the full picture.

  • The server can sign people in to Google: either through Control Center Connect, or with the server’s own Google client (Bring your own Google client). The server owner chooses in Settings → Server → Single sign-on
  • A workspace open: a calendar account always belongs to one
  1. Open Calendar in the sidebar.
  2. Click Add calendar account in the calendar sidebar. (The same section lives at Settings → You → Profile, under Google Calendar.)
  3. Click Connect Google Calendar. Your browser opens Google’s consent page.
  4. Choose the account and approve access to your calendar events and calendar list.

How it finishes depends on who runs the sign-in:

  • The server’s own Google client: Google sends your browser back to the server and the dialog closes on its own
  • Control Center Connect: the browser page shows an 8-character code. Type it into the dialog, or let the browser open Control Center through the control-center:// link and skip typing it

Your events begin syncing straight away. The server, not your device, finishes the exchange and keeps the credential.

The account is connected to the active workspace only, and it is yours: two members who connect the same Google address get separate accounts. Switch workspaces and you’ll see that workspace’s calendars instead.

The connect flow requests calendar.events and calendar.calendarlist.readonly plus openid email, whichever client runs it. An account connected before Control Center could write to Google has only the read-only scope; it asks you to reconnect, and the new sign-in grants the rest.

  • Book an event: in the week or day view, drag across the time grid to draw the span (in the month view, drag across days for an all-day event). A card opens beside it with the title, times, guests, a Google Meet link, location, description and which calendar to book on. Save books it on Google and opens it. The + button in the calendar header opens the same card for the next free quarter hour. Press Escape to drop it
  • Move an event: drag it to another time or day, or drag its bottom edge to change when it ends. It opens once Google has the new time; if Google refuses, it goes back where it was. You can move your own events and the ones you organise; an invitation stays where its organiser put it
  • Answer an invitation: open the event and choose Yes, Maybe or No
  • Delete an event: open it and click the trash icon. The confirmation says who is affected: guests are told an event you organise is cancelled, while deleting an invitation removes it from your calendar only. Deleting one occurrence of a recurring event leaves the rest of the series

Guests receive Google’s own email invitation, update or cancellation, and moving one occurrence of a recurring event leaves the rest of the series. You can only book on calendars your account may write to, and only with your own accounts: another member’s connected calendar is never offered.

The server owns the schedule: it sweeps every workspace’s connected accounts every two minutes and writes the events into the workspace’s database. Clients never talk to Google — they read what the server wrote.

The sweep is incremental. The first pass per calendar fetches a rolling window (60 days back, 90 days ahead) and captures Google’s sync token; later passes present that token and receive only what changed, which is what makes a two-minute cadence affordable. The window is re-anchored with a full sync every 24 hours and whenever Google invalidates the token.

Credentials live server-side in secrets.json under the server’s data directory, written owner-only (0600) — not in the OS keychain and never on a client device. A sign-in through Connect stores only a sealed credential that Connect can open for this server alone; its access token stays in the server’s memory.

A workspace can connect several Google accounts (for example work and personal). Repeat the connect step for each; their events merge into the same month / week / agenda views. Each account syncs and refreshes independently and each can be disconnected on its own.

If Google permanently invalidates an account’s sign-in (a revoked or long-expired session), syncing stops and Control Center shows a Reconnect banner on the calendar, plus a desktop notification. Click Reconnect and sign in again; the banner clears on the next successful sync.

The same banner appears when the sign-in can no longer be used by this server: the server owner switched Connect servers or rotated the Connect key, the server’s own Google client changed, or the data directory was restored onto another machine.

From the calendar sidebar (or Settings → You → Profile), click Disconnect on the account. This deletes its synced events and clears its stored credential on the server.

Run your own Google client when you chose Use my own apps. The server’s own client applies only then: with Control Center’s or a custom Connect, Connect runs every lane, Google included, and the server’s client stays saved but unused. To have the consent screen name your own project while the server uses Connect, put the workspace on its own apps and give it its own client (below); that applies whatever the server’s mode.

  1. In the Google Cloud Console, enable the Google Calendar API and configure the OAuth consent screen, adding the calendar.events, calendar.calendarlist.readonly, openid and email scopes. While the app is unverified, add yourself as a test user.
  2. Create an OAuth client ID of application type Web application.
  3. Add the authorised redirect URI <server origin>/oauth/google/callback. Settings → Server → Single sign-on → Provider apps → Google shows the exact URL under Callback URLs; copy it verbatim.
  4. Paste the Client id and Client secret into that same Google block, or put them in the server’s .env file as GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET.

The server refuses to start when GOOGLE_OAUTH_CLIENT_SECRET is exported in its process environment; keep it in the .env file (in Docker, mount it at /app/bin/.env). The secret never leaves the server: no RPC response carries it. A client id without its secret is an unfinished setup, and Google sign-ins are refused until both are set.

Changing to a different client signs everyone out of Google Calendar: a sign-in belongs to the client that issued it.

A workspace can connect Google Calendar through a client of its own instead of the server’s. Only a workspace admin or owner can set it up.

  1. Create a Google Web application client as in steps 1 and 2 above
  2. Go to Settings → Workspace → Integrations. On the Control Center Connect card, choose Use my own apps and click Apply
  3. Under Calendar, the Google Calendar app card appears. Add the redirect URI it shows under Callback URL to the client, verbatim
  4. Paste the Client id and Client secret

Calendar accounts connected in this workspace then go through that client, whichever way the server signs people in. It never falls back to the server’s client or to Connect: until both fields are set, Google Calendar is off in this workspace and the card says what is missing. The secret never leaves the server.

Use my own apps covers every provider at once: GitHub, Linear and GIF search also run only on the workspace’s own apps. Switching the workspace’s sign-in apps, or changing the workspace’s client id, marks every Google account in this workspace for reconnection. The saved fields stay when the workspace switches back to another choice, but are used only under Use my own apps. Other workspaces on the server are not affected.

Symptom Likely cause
Connect Google Calendar says sign-in isn’t set up The server has neither its own Google client nor Connect. The server owner picks one in Settings → Server → Single sign-on
Google shows redirect_uri_mismatch The redirect registered on the client does not match the Callback URLs value exactly, or the server’s public URL changed
invalid_client from Google The id and secret are from different clients, or the client was deleted
Approval succeeds but sync is empty Your account is not a test user on the consent screen, or a requested scope was not granted
The dialog says the code does not match Type the 8 characters exactly as the browser shows them. Five wrong codes end the sign-in; start again
“Couldn’t update your response”, or booking, moving or deleting fails The account did not grant calendar write access. Reconnect it and approve every requested scope; a calendar shared with you read-only also refuses writes
Everybody has to reconnect The server’s or the workspace’s Google client changed, or the server’s or the workspace’s Connect choice, or the server’s key, changed. See Reconnect an expired account