> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobalt.peoplereign.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace

> Connect Gmail, Drive, Docs, Sheets, and Calendar — reads in a minute, plus admin actions.

# 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

| Module        | What the agent can do                                               |
| ------------- | ------------------------------------------------------------------- |
| Gmail         | Search and read threads; draft and send (when enabled)              |
| Drive         | Search files and read metadata and contents                         |
| Docs          | Read documents                                                      |
| Sheets        | Read sheet values                                                   |
| Slides        | Read presentations                                                  |
| Calendar      | List and read events                                                |
| Admin actions | Reset a password, add a user to a group, suspend a user — see below |

## Set up read access

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Steps>
  <Step title="Create a service account and key">
    In Google Cloud, create a service account and generate a **JSON key**.
    Download the key file.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Note an admin to act as">
    Choose a Workspace super-admin account the service account will impersonate
    when it performs actions.
  </Step>
</Steps>

### In Cobalt

<Steps>
  <Step title="Open the integration's authorization settings">
    On the Google Workspace integration, go to the authorization section for admin
    actions.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Verify">
    Run verify. Cobalt makes a live call to confirm the delegation works and shows
    who granted it and when.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Warning>
  **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.
</Warning>

* **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.

## Related

* [Integrations overview](/integrations/overview) — how integrations work in
  general.
* [How Cobalt works](/concepts/how-cobalt-works) — where integrations fit.