Google Account Connection
Each CalGrid workspace connects to a separate Google account via OAuth 2.0. This page explains how to connect, verify, and manage your Google account per workspace.
Overview
CalGrid uses the official Google Desktop OAuth 2.0 flow to access your Google Calendar. Your account credentials are stored securely in Windows Credential Manager — never in any file on disk.
Connecting a Google Account
Requirements
Before connecting, you need:
- A Google Cloud project with the Calendar API enabled
- An OAuth 2.0 Desktop client JSON file downloaded from Google Cloud Console
If you have not completed this setup yet, see Google API Setup.
Connection Steps
- In the left sidebar, find the Google Auth section.
- Click + Add (or ✓ JSON if a file was previously selected).
- A file picker opens — navigate to and select your OAuth client JSON file.
- The button changes to ✓ JSON and shows the filename on hover.
- Click 🔗 Connect.
- Your default browser opens the Google sign-in page.
- Sign in with your Google account.
- Grant CalGrid the requested Calendar permissions when prompted.
- After authorization, the browser closes or shows a confirmation message.
- Return to CalGrid — the sidebar now shows 🔓 Disconnect and the title bar shows your account email with a green dot.
Connection Status Indicators
| Sidebar Button Text | Title Bar Dot | Meaning |
|---|---|---|
| + Add | Grey | No JSON file selected |
| ✓ JSON + 🔗 Connect | Grey | JSON loaded, not yet authorized |
| ⏳ Verify… | Grey | Checking saved credentials on startup |
| ⏳ Wait… | Grey | OAuth browser flow in progress |
| 🔓 Disconnect | Green (✓ email) | Connected and authorized |
Automatic Credential Restoration
When CalGrid starts, it automatically checks saved credentials for every workspace in the background:
- CalGrid reads the stored OAuth token from Windows Credential Manager.
- If the token is valid, the workspace is marked connected — no browser prompt required.
- If the token has expired or was revoked, the workspace shows 🔗 Connect and you must re-authorize.
This check takes a few seconds. The sidebar shows ⏳ Verify… briefly during this process.
Disconnecting a Google Account
- In the left sidebar, click 🔓 Disconnect.
- The stored token is immediately deleted from Windows Credential Manager.
- The sidebar returns to 🔗 Connect state.
You can reconnect at any time by clicking 🔗 Connect again.
Reselecting a JSON File
If you need to use a different OAuth JSON file (e.g., after recreating credentials in Google Cloud):
- Click the ✓ JSON button in the sidebar.
- A file picker opens — select the new JSON file.
- Click 🔗 Connect to authorize with the new credentials.
Service Account JSON (Advanced)
CalGrid accepts Service Account JSON files in addition to Desktop OAuth client files. Service accounts require Google Workspace domain-wide delegation to send invitations from other users’ calendars.
For standard personal Google accounts, always use a Desktop OAuth client JSON.
Security Notes
- OAuth tokens are stored in Windows Credential Manager under the key
CalGrid.OAuth.v1. - Tokens are tied to your Windows user account and cannot be read by other users on the same machine.
- CalGrid never stores your Google password.
- Disconnecting removes the stored token permanently.