Configure Google Cloud OAuth credentials so your self-hosted DiviDen instance can connect to Gmail, Google Calendar, and Google Drive. This guide walks through every step from creating a Google Cloud project to verifying the connection.
Go to the Google Cloud Console — New Project page.
Enter a project name. Something like DiviDen Instance or MyOrg DiviDen works fine. The name is for your reference only.
Select your organization (if applicable) or leave as "No organization".
Click Create. Wait for the project to be provisioned (a few seconds).
Make sure the new project is selected in the project dropdown at the top of the console. All subsequent steps must be done within this project.
DiviDen needs three Google APIs enabled. You can enable them one by one from the API Library, or use the direct links below.
Read, send, and compose emails
Full read and write access to calendar events
Read-only access to files and folders
The consent screen is what users see when they authorize DiviDen to access their Google data.
Select External user type (unless your Google Workspace org restricts it to Internal). Click Create.
Fill in the app information:
| App name | DiviDen (or your instance name) |
| User support email | Your admin email address |
| App logo | Optional — upload your instance logo if desired |
| Developer contact | Your admin email address |
On the Scopes page, click Add or Remove Scopes and add these seven scopes:
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive.readonly
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profileYou can paste these into the "Manually add scopes" field, one per line, then click Add to Table.
On the Test users page, add the Google accounts that will connect to your instance. While the app is in "Testing" publishing status, only these accounts can authorize.
Click Save and Continue through the remaining screens, then Back to Dashboard.
Click + Create Credentials → OAuth client ID.
Set Application type to Web application.
Give it a name (e.g., DiviDen OAuth).
Under Authorized redirect URIs, click + Add URI and enter:
https://your-domain.com/api/auth/callback/google-connectReplace your-domain.com with your actual instance domain. If you access your instance at https://dividen.mycompany.com, the redirect URI would be https://dividen.mycompany.com/api/auth/callback/google-connect.
Click Create. Google will display your Client ID and Client Secret. Copy both values immediately — you will need them in the next step.
Authorized JavaScript origins — DiviDen uses server-side OAuth and does not need them. Adding incorrect origins can cause unexpected errors.123...apps.googleusercontent.com)GOCSPX-...)Add the credentials to your DiviDen instance's environment. How you do this depends on your deployment method.
Add these to your .env file or docker-compose.yml environment section:
GOOGLE_CLIENT_ID=your-client-id-here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret-hereAdd to your .env file in the project root:
GOOGLE_CLIENT_ID=your-client-id-here.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-client-secret-hereAdd both variables to your platform's environment/secrets configuration. The exact location varies by platform but is typically under Settings → Environment Variables.
Restart your DiviDen instance so it picks up the new environment variables.
docker compose restart# Stop the running process, then:
yarn build && yarn startLog in to your DiviDen instance and go to Settings → Integrations.
Click Connect Google. You should be redirected to Google's consent screen.
Select the Google account you want to connect and authorize all requested permissions.
You will be redirected back to DiviDen. If successful, you will see connected status indicators for Gmail, Calendar, and Drive in the Integrations panel.
DiviDen requests seven OAuth scopes. Here is what each one does:
| Scope | Service | Access Level | Used For |
|---|---|---|---|
| gmail.readonly | Gmail | Read | Sync inbox, read email threads |
| gmail.send | Gmail | Write | Send emails via agents |
| gmail.compose | Gmail | Write | Draft and compose emails |
| calendar | Calendar | Read + Write | Sync events, create meetings |
| drive.readonly | Drive | Read | Sync files and folders |
| userinfo.email | Identity | Read | Identify the Google account |
| userinfo.profile | Identity | Read | Display name and avatar |
This is the most common error. It means the redirect URI configured in Google Cloud does not exactly match what DiviDen sends.
Check these:
https://your-domain.com/api/auth/callback/google-connecthttps:// (not http://)www. vs non-www.)This usually means the OAuth consent screen is not fully configured. Go back to the consent screen settings and make sure:
DiviDen requires offline access (refresh tokens) to maintain persistent connections. If you previously authorized the app and then revoked access, Google may not issue a new refresh token.
Fix:
prompt: consent and access_type: offline in the OAuth flow, which should force a refresh token on every authorization. This issue is rare but can happen if Google's token cache is stale.This means your instance cannot find the GOOGLE_CLIENT_ID and/or GOOGLE_CLIENT_SECRET environment variables.
echo $GOOGLE_CLIENT_ID.env file is mounted or variables are passed via -e flagsCheck the browser console and server logs for errors. Common causes:
By default, your Google Cloud OAuth app is in Testing status. This means:
For a personal or small-team instance, Testing status is usually fine — just add all team members as test users. If you need wider access or tokens that do not expire:
GOOGLE_CLIENT_SECRET to version control. Use environment variables or secrets management.Users can revoke DiviDen's access at any time from Google Account → Third-party apps. DiviDen also provides a Disconnect button in Settings → Integrations.
Download a plain-text copy of this page
Last updated: May 27, 2026
Built by DiviDen — the individual-first operating system