Caddi connects to Google Workspace through an OAuth 2.0 client you create in your own Google Cloud project. Each of your users then authorizes their own Google account, so Caddi sees only what that person can see.
Google renamed part of this interface. What older documentation calls APIs & Services → OAuth consent screen is now the Google Auth Platform, with Overview, Branding, Audience, Clients, Data Access, and Verification sub-pages.
If your project sits under a Google Cloud Organization, set the audience to Internal. Internal apps skip Google's verification process entirely, including the security assessment that restricted scopes otherwise trigger. This is the single most important decision in this setup.
If you need Caddi to act without a person authorizing — for example a scheduled loop that runs as a service — use the Google Service Account setup instead.
Before you start
You'll need:
A Google Cloud project, and Owner or Editor on it
Owner or Admin access to your Caddi organization
To know whether your project belongs to a Google Cloud Organization — this determines whether Internal audience is available
No billing account is required. The Gmail, Drive, Calendar, Docs, Sheets, and Admin SDK APIs used here are all free-tier.
Step 1: Create the project and enable the APIs
Create or select a project at console.cloud.google.com.
Go to APIs & Services → Library and filter to Google Workspace.
Enable each API your loops need:
Gmail API — for reading, drafting, and sending mail
Google Drive API — for files and folders
Google Calendar API — for events
Google Docs API and Google Sheets API — for documents and spreadsheets
Admin SDK API — only if a loop needs to enumerate domain users or groups
Assign project Owner to a second person as well. An orphaned Google Cloud project takes the credentials with it.
Step 2: Configure the Google Auth Platform
Go to Google Auth Platform → Branding. Click Get Started if it's unconfigured.
App name —
Caddi. This appears on the consent screen your users see.User support email — required.
Go to Audience and choose Internal if your project is under a Google Cloud Organization and only your own Workspace accounts will connect. Choose External otherwise.
Contact Information — a developer email for Google's notices. Required.
Accept the Google API Services User Data Policy and click Create.
External only: under Branding, add
trycaddi.comto Authorized domains. Internal apps don't need this.Go to Data Access → Add or Remove Scopes, select the scopes (see below), then Update and Save.
Step 3: Choose scopes
Google classifies scopes as non-sensitive, sensitive, or restricted. The class matters a great deal for External apps and not at all for Internal ones.
gmail.modify and drive are restricted scopes. For an External app they trigger Google review plus an independent third-party security assessment, reverified annually — expect real cost and a multi-week timeline. For an Internal app they work immediately with no verification and no warning screen.
For full read and write across Workspace:
https://www.googleapis.com/auth/gmail.modify— read, compose, and send mailhttps://www.googleapis.com/auth/drive— full Drive accesshttps://www.googleapis.com/auth/calendar.events— read and write eventshttps://www.googleapis.com/auth/documents— read and write Docshttps://www.googleapis.com/auth/spreadsheets— read and write Sheets
A lower-privilege alternative that avoids all restricted scopes:
https://www.googleapis.com/auth/gmail.sendinstead ofgmail.modifyhttps://www.googleapis.com/auth/drive.fileinstead ofdrive— but note this reaches only files the user explicitly opens with Caddi or that Caddi created, which is a real functional limit, not just less paperworkCalendar, Docs, and Sheets scopes as above
Step 4: Create the OAuth client
Google hashes client secrets. You can view and download the full secret only once, at creation. Afterwards the console shows only the last four characters, and recovery means creating a new secret.
Go to Google Auth Platform → Clients and click Create Client.
Application type — Web application.
Name it
Caddi.Under Authorized redirect URIs, click + Add URI and paste
https://app.trycaddi.com/oauth-callbackexactly.Leave Authorized JavaScript origins empty — Caddi uses a server-side flow.
Click Create.
Copy the Client ID and Client secret from the modal now, or use Download JSON.
The redirect URI must match byte-for-byte what Caddi sends. A trailing slash, http instead of https, or a difference in case all produce redirect_uri_mismatch.
Step 5: Configure Google in Caddi
This step must be completed by a Caddi organization owner or admin.
In Caddi, open Integrations in the left sidebar, then click the Integration Setup tab at the top of the page. This tab is only visible to organization owners and admins.
Find Google in the list and click Configure.
Enter the following values:
Client ID — ends in
.apps.googleusercontent.comClient Secret — begins with
GOCSPX-. Available only at creation time.OAuth Scopes — space-separated list matching what you configured on the consent screen. Leave blank to use Caddi's defaults.
Click Save Configuration. Caddi validates the credentials immediately — if something is wrong you'll see an error right away, and nothing is stored until validation passes.
Step 6: Connect your account
Go back to the My Connections tab and find Google.
Click Connect + and sign in to Google.
Review what Caddi is requesting and click Allow.
You'll be returned to Caddi with the connection active.
How the connection behaves
Each user connects their own Google account. Caddi acts on behalf of that user and sees only their mail, files, and calendar.
A custom connection replaces the standard one — and collapses the individual Google connectors. Once you configure a custom Google integration, members of your organization no longer see separate Gmail, Drive, Calendar, Docs, or Sheets options; they see one Google connection.
External + unverified means a warning screen. Users see "Google hasn't verified this app" and have to click through Advanced → Go to (unsafe). That's not acceptable for a production rollout, which is why Internal is strongly preferred.
External apps requesting unapproved sensitive or restricted scopes are capped at 100 new users. This is a lifetime, project-wide limit that cannot be reset or raised, and exhausting it can result in Google sign-in being disabled for your users. Monitor it under Google Auth Platform → OAuth user cap status.
Do not leave the app in Testing mode. Authorizations by test users expire seven days after consent, refresh tokens included. Publish it, or use Internal audience.
Refresh tokens can also break on user revocation, some password changes, six months of non-use, or exceeding the per-user refresh-token limit for the client.
Revoking access. Delete the OAuth client in Google Cloud Console, or have users revoke Caddi from their Google account permissions.
Troubleshooting
redirect_uri_mismatch at sign-in
The Authorized redirect URI doesn't match https://app.trycaddi.com/oauth-callback byte-for-byte. Check for a trailing slash, http vs https, and case.
Users see "Google hasn't verified this app"
The app is External and unverified. Switch the audience to Internal if your project is under a Google Cloud Organization — that removes the warning entirely. Otherwise you'll need to complete Google's verification.
Connections stop working about a week after setup
The app is in Testing mode, where authorizations and refresh tokens expire after seven days. Publish the app or switch to Internal audience.
New users suddenly can't connect
You've likely hit the 100-user lifetime cap for an External app with unapproved sensitive or restricted scopes. The cap cannot be reset — switch to Internal audience, or complete Google verification.
The client secret was lost
Google hashes secrets and shows them once. Create a new secret on the client and update the configuration in Caddi.
A loop can't reach files the user clearly owns
The drive.file scope was selected instead of drive. drive.file only reaches files the user explicitly opened with Caddi or that Caddi created. Switch to drive and have users reconnect.
Still stuck? Contact Caddi support with the exact error message you're seeing and the time it occurred.
Automation ideas
Law Firms
Inbound email → matter filing
Caddi reads incoming client mail, determines the matter, files attachments to the right Drive folder, and logs the correspondence.
Calendar event → time entry
Caddi reads meeting duration and attendees from Calendar, drafts the narrative, and creates the time entry in your practice management system.
Template + matter data → drafted document
Caddi merges matter data into a Google Docs template, produces the draft, and files it for review.
RIAs
Client email → CRM activity log
Caddi logs client correspondence to the CRM contact record so the relationship history is complete without anyone forwarding anything.
Quarterly data → reporting workbook
Caddi assembles performance data into a Sheets workbook and files the generated reports into each client's Drive folder.