How to Connect Google Workspace
Connect your Google account to CRHQ so your AI agents can work with Gmail, Calendar, Drive, Sheets, and more — on your behalf.
Overview
CRHQ agents can work with your Google Workspace services — reading emails, managing calendar events, creating documents, and more. To enable this, you connect your Google account through a secure OAuth flow. You choose exactly which services to authorize.
The Google Workspace Connector
When you open the Google Workspace connector in Settings > Connectors, you'll see a modal with two tabs:
- Accounts — Connect and manage your Google accounts
- App — Configure which Google OAuth app to use (CRHQ default or your own)
Before You Start
- You need a Google account (personal Gmail or Google Workspace)
- You need admin access to your CRHQ satellite (the Settings page)
- You need a Google OAuth app configured — either set up your own (recommended) or wait for the CRHQ app to complete verification. See How to Set Up a Custom Google App for a step-by-step guide.
- If your organization uses Google Workspace, your admin may need to allow third-party apps
Step-by-Step: Connect Your Account
1. Open the Connector
Navigate to Settings > Connectors and click on Google Workspace. You'll land on the Accounts tab.
2. Click Connect
Click the Connect button. A scope picker will appear showing all available Google services.
3. Choose Your Permissions
Select only the services you need:
| Service | What It Allows | Scope |
|---|---|---|
| Gmail | Read, compose, and send emails | gmail.modify |
| Calendar | View and manage calendar events | calendar |
| Drive & Docs | Create, read, and edit Drive files and Google Docs | drive, documents |
| Sheets | Create and edit spreadsheets | spreadsheets |
| Slides | Create and edit presentations | presentations |
| Analytics | View website traffic data (read-only) | analytics.readonly |
| Search Console | View SEO data (read-only) | webmasters.readonly |
| AdSense | View ad earnings (read-only) | adsense.readonly |
| Google Ads | Manage ad campaigns | adwords |
Tip: Only select what you actually need. You can always reconnect later to add more services.
Tip: If you're using your own Google Cloud app, make sure the APIs for your selected services are enabled in your project's API Library. Google will silently skip any scopes your app doesn't support — the connection will succeed, but agents won't be able to use those services. See Scope Behavior with Custom Apps below.
4. Pick Your Google Account
After clicking "Connect with N services", Google's account chooser will appear. Select the Google account you want to connect — this is where you pick your work account vs personal account.
5. Grant Consent
Google will show you exactly what permissions you're granting. Review them and click Allow. You'll be redirected back to CRHQ with a success confirmation.
6. Verify
Back in Settings > Connectors > Google Workspace > Accounts, you should see your connected account listed with the email address.
Connecting Multiple Accounts
You can connect more than one Google account. Just click Connect again and choose a different account. This is useful if you need agents to work with both a personal and work account, or multiple client accounts.
Each connected account is stored separately and agents can specify which account to use.
The App Tab
The App tab lets you choose which Google OAuth app handles your connections. There are two options:
CRHQ App (Default)
The shared CRHQ Google app. Currently awaiting Google's verification review — during this period, new connections cannot use this app. Once verified, it will work out of the box with no setup required.
Custom App (Recommended)
Use your own Google Cloud project for full control. This is the recommended approach — it gives you:
- Immediate access (no waiting for verification)
- Full control over which APIs are enabled
- Your own OAuth consent screen branding
- Independent quota and rate limits
To set up a custom app, follow the guide: How to Set Up a Custom Google App.
Scope Behavior with Custom Apps
When using your own Google Cloud app, the scope picker in CRHQ shows all services that CRHQ supports. However, your app will only grant access to APIs you've actually enabled in your Google Cloud project.
What happens if there's a mismatch:
- You select Gmail + Calendar + Drive in the CRHQ scope picker
- Your Google Cloud project only has Gmail and Calendar APIs enabled
- The OAuth flow completes successfully — no error
- Google silently drops the Drive scope
- Your agent can use Gmail and Calendar, but Drive requests will fail with a 403 error
How to avoid this: Enable all the APIs you need in your Google Cloud project's API Library before connecting. The Custom Google App guide includes the full list of APIs to enable.
Using Google Services with Agents
Once connected, agents with the relevant Google skills can access your authorized services. For example:
You: "What's on my calendar today?"
Agent: [Uses google-calendar skill to list today's events]
You: "Draft a reply to the latest email from John"
Agent: [Uses google-gmail skill to read and compose]
You: "Create a spreadsheet with this month's sales data"
Agent: [Uses google-sheets skill to create and populate]
The agent will use the first connected Google account by default. If you have multiple accounts, you can tell the agent which one to use:
You: "Check the calendar for john@company.com"
Troubleshooting
"Access blocked: This app's request is invalid"
This usually means the OAuth configuration has an issue. If you're using a custom app, verify:
- The redirect URI is set to
https://crhq.ai/auth/google/proxy-callback - The OAuth consent screen is configured
- The app is set to "External" user type (or "Internal" if using Google Workspace)
"redirect_uri_mismatch"
The redirect URI in your Google Cloud project doesn't match what CRHQ sends. Make sure your authorized redirect URI is exactly:
https://crhq.ai/auth/google/proxy-callback
Agent says "No Google account connected"
Make sure you've connected your account in Settings > Connectors > Google Workspace > Accounts. The connector must be active and have at least one credential stored.
Agent gets "unauthorized" or 403 errors
This can mean:
- Token expired — Disconnect and reconnect your Google account
- Missing API — If using a custom app, the API for that service isn't enabled in your Google Cloud project. Go to API Library and enable it.
- Scope not granted — You didn't select that service when connecting. Reconnect with the additional scope selected.
Can't see the account chooser
If Google skips the account chooser and auto-selects your default account, try:
- Opening the connect link in an incognito/private window
- Going to myaccount.google.com first and switching to the desired account
Security & Privacy
What data does CRHQ access?
Only the services you explicitly authorize. If you only select Calendar, CRHQ cannot read your emails or Drive files.
How are credentials stored?
Your OAuth tokens are encrypted using AES-256-GCM encryption on your dedicated CRHQ satellite server. Tokens are never sent to CRHQ's central servers or any third party.
Can I revoke access?
Yes, at any time:
- From CRHQ: Delete the credential in Settings > Connectors > Google Workspace > Accounts
- From Google: Go to myaccount.google.com/permissions and remove the app from connected apps
Does CRHQ store my emails/files?
No. Agents read and process data in real-time during conversations. Your emails, calendar events, and files are not stored in CRHQ's database. Only the OAuth tokens (for authentication) are stored.
Best practices
- Grant minimum permissions — only select the services your agents actually need
- Review connected apps periodically — check your Google account permissions regularly
- Use a work account for work tasks — keep personal and work data separate
- Disconnect unused accounts — if you no longer need an agent to access a Google account, remove it