> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Your Google OAuth client
> GainTrace connects Gmail and Google Calendar through an OAuth client your own Google Workspace organization owns. You hold the keys, you set the audience, and you can revoke access yourself at any time.
GainTrace does not operate a shared Google app. Connecting Gmail or Google Calendar runs through an OAuth client that your Google Workspace organization creates and owns, and every workspace sets up its own.
That means there is no GainTrace-held Google credential sitting between you and your mailboxes. Your IT team owns the app your people consent to, decides who may use it, and can switch it off without asking us.
## Why we built it this way
Most tools ask you to trust one vendor-owned app that every customer shares. We think that is the wrong shape for mailbox access, and Google's own rules push the same direction: reading Gmail uses scopes Google classifies as restricted, and a shared public app requesting them carries a much larger blast radius.
An OAuth client you own changes five things:
| Property | What it means for you |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **You own the consent screen** | Your people consent to an app registered in your organization, not to a third party. |
| **Internal audience** | With the consent screen set to **Internal**, the app cannot be used by anyone outside your organization. Not by us, not by another customer, not by an attacker with a stolen link. |
| **You revoke, unilaterally** | Disable or delete the client in your Google Cloud Console and every token dies immediately. No support ticket, no waiting on our deploy schedule. |
| **Your audit trail** | Grants, consents, and API activity appear in your own Google Cloud audit logs, where your security team already looks. |
| **No shared blast radius** | No client is shared between customers. A credential problem in one organization cannot reach another, because there is no common key to compromise. |
To be precise about what this does and does not cover: owning the client controls **authorization**, who may connect and how access is revoked. It does not change where matched email is stored. GainTrace still holds the customer email it captures, under the rules described in [Connect email and calendar](/help/integrations/email-calendar). Client ownership makes the door yours; it does not make the room empty.
## Before you start
You need all three:
| Requirement | Why |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| A **Google Workspace** organization | Only an organization-owned project can set its consent screen to **Internal**. A personal Gmail account cannot. |
| Access to **Google Cloud Console** for that organization | You create the project and the OAuth client there. |
| **Owner** or **Admin** in GainTrace | Saving the client requires settings permissions. Other members can see the panel but not edit it. |
Google Workspace is required. A personal Gmail account cannot select **Internal**, which leaves the client in testing mode, and Google expires refresh tokens issued in testing mode after 7 days. Everyone would have to reconnect weekly.
## What GainTrace asks for
Review these before you create the client. Your organization owns the consent decision, so it is worth knowing exactly what you are granting:
| Scope | What it is for |
| ------------------------------------ | ------------------------------------------------------------------------------------- |
| `gmail.readonly` | Read matched email so it appears on Company timelines and feeds sentiment and signals |
| `gmail.send` | Let your team reply in-thread from GainTrace |
| `gmail.settings.basic` | Read the mailbox signature so replies match what people send from Gmail |
| `calendar.readonly` | Read meetings so they appear on Company timelines |
| `userinfo.email`, `userinfo.profile` | Identify the connected mailbox and show its name and avatar |
Nothing here writes to your mailbox except `gmail.send`, and that only fires when a person clicks send in GainTrace. Nothing deletes, and nothing changes settings.
GainTrace also discards most of what it reads. Only email involving a known Company domain or a saved Person is stored; everything else is dropped during sync.
## Set up your client
Go to **Settings > Email & Calendar** and click the **Google Workspace** tile under **Add Connection**. The guided setup opens in place, with a link to the right Google Cloud Console page at every step. Keep it open, you will copy a redirect URI from it in step 5.
In Google Cloud Console, create a project owned by your organization, then enable the **Gmail API** and the **Google Calendar API**.
Under **APIs & Services > OAuth consent screen**, choose **Internal**. This is what confines the app to your organization, so do not skip it.
Under **Credentials**, create an **OAuth client ID** of type **Web application**.
Copy the URI shown under **Authorized redirect URI** in the GainTrace panel and paste it into **Authorized redirect URIs** on your client. This stays a GainTrace URL. Your client points back to GainTrace after someone consents, so there is nothing to host on your side.
Paste the client ID and client secret into the setup, then click **Save and continue**. The secret is encrypted before it is stored and is never shown again.
Saving takes you straight to **Connect your mailbox**, so setup ends in a working connection rather than a saved form. Everyone else connects from the same Google Workspace tile.
Microsoft 365 is unaffected and connects normally, with no client setup of its own.
## Rotate your client
Open the Google Workspace tile, click **Replace**, then paste a new client ID and secret.
Existing connections keep working. Google ties a refresh token to the client that issued it, so GainTrace keeps refreshing each connection against the client it was authorized under, not whichever client is current. Nobody is logged out and no sync breaks.
Those connections stay on the previous client until each person reconnects, though. The panel shows how many are in that state as **still on a previous client**.
Reconnect everyone before you delete the old client in Google Cloud Console. Deleting it there does break their refresh, and GainTrace cannot repair it for them.
## Remove your client
Open the Google Workspace tile, click **Remove**, and confirm.
There is nothing to fall back to, so this ends the workspace's ability to connect Google entirely. Every mailbox authorized through the client is disconnected, because those tokens are only valid for the client being removed and leaving them connected would mean syncs that quietly stop working. The confirmation dialog tells you exactly how many connections will be disconnected before you commit.
Email already captured stays on your Company timelines.
## Good to know
* Gmail and Google Calendar share one client. Setting it up covers both.
* Microsoft 365 needs none of this. Microsoft has no equivalent restriction, so Outlook connects with no extra setup.
* The client ID is not a secret. It appears in the consent URL, so every member can see it in the panel. The client secret is encrypted at rest and never returned to the browser after you save it.
* One client serves the whole workspace. Each person still connects their own mailbox individually.
* Google sets the rules for consent screens and scopes, and can change them. The behavior described here reflects Google's documentation as of August 2026.
## FAQ
**Can I use GainTrace's client instead?**
There isn't one. Every workspace connects Google through a client it owns.
**Can I use a personal Gmail account?**
No. Only a Google Workspace organization can set a consent screen to **Internal**. Without it, Google expires refresh tokens after 7 days and everyone reconnects weekly.
**How do I cut off GainTrace's access immediately?**
Disable or delete the OAuth client in your Google Cloud Console. Every token stops working at once, with no action needed from us. You can also remove the client inside GainTrace, which disconnects every mailbox.
**Will people have to reconnect after I rotate the client?**
Not immediately. Existing connections keep syncing on the client that authorized them, and move across the next time each person reconnects.
**Can regular members set this up?**
No. Saving or removing the client requires Owner or Admin. Members see the panel read-only.
**Does this mean GainTrace cannot read my email?**
It means GainTrace can only read it while your client grants access, and only the messages involving your Companies and People. Everything else is discarded at sync time.
## Related articles
Connect a mailbox, and what GainTrace does and does not store.
Owner and Admin roles, and who can change workspace settings.
How GainTrace handles your workspace data.
Browse the catalog and manage your connected sources.