Skip to main content

​
Google Workspace

The Google Workspace integration gives an agent read access to Gmail, Drive, Docs, Sheets, Slides, and Calendar, and — when you enable it — privileged admin actions like resetting a password or adding a user to a group. This page walks through both. Read access takes about a minute and needs nothing in the Google Admin console. Admin actions need a one-time setup in Google.

​
Modules

​
Set up read access

1

Add the integration

From your agent, open Integrations, choose Google Workspace, and select the modules you want. HR agents often skip Gmail; IT agents often keep Drive and Calendar.
2

Attest to the access requested

Review the read scopes (Gmail, Drive, Calendar, and so on). The higher-impact ones are flagged. Confirm, name the integration, and save.
3

Let users authorize themselves

The first time the agent uses a Google tool for someone, that person is asked to authorize with Google. From then on the agent acts as them and sees only what they can already see.
That’s it — there’s no Google Cloud setup for reads. Cobalt hosts the connection.

​
Set up admin actions (optional)

Admin actions act on your whole Workspace, so they use a Google service account with domain-wide delegation. You do part of this in Google and part in Cobalt.

​
In the Google Admin and Cloud consoles

1

Create a service account and key

In Google Cloud, create a service account and generate a JSON key. Download the key file.
2

Grant domain-wide delegation

In the Google Admin console, authorize the service account’s client ID for the admin scopes you need — directory user and directory group.
3

Note an admin to act as

Choose a Workspace super-admin account the service account will impersonate when it performs actions.

​
In Cobalt

1

Open the integration's authorization settings

On the Google Workspace integration, go to the authorization section for admin actions.
2

Upload the key and name the subject

Paste or upload the service-account JSON key and enter the super-admin email to impersonate. The key is encrypted at rest and never shown again.
3

Verify

Run verify. Cobalt makes a live call to confirm the delegation works and shows who granted it and when.
4

Set allowlists

For actions like adding a user to a group, list the groups the agent is allowed to manage. Actions outside the allowlist are denied or routed to a human.
Once configured, the admin tools become available on the agent, every action runs under policy, and each one is written to the audit trail.

​
Common pitfalls

Missing scopes. If verify fails, the service account’s client ID usually hasn’t been authorized for the directory scopes in the Google Admin console. The error names the scopes it’s missing.
  • Wrong subject. The impersonated account must be a Workspace super-admin, or privileged calls will be rejected.
  • Key rotation. Service-account keys age out. When prompted, generate a new key in Google Cloud, grant delegation to the new client ID, then upload and re-verify in Cobalt.