Cotool + Google Workspace
Connect Google Workspace to Cotool so agents read audit logs and Alert Center alerts, investigate risky OAuth grants, and reset user passwords with approval.
The short answer
With Google Workspace connected through domain-wide delegation, Cotool agents read Workspace audit logs and Alert Center alerts, investigate risky OAuth grants, author detections on Workspace activity, and reset a user's password as a response action.[1][2][3]
How it connects: Cotool uses Google Workspace domain-wide delegation. A super administrator authorizes the client ID of a service account or OAuth app for specific scopes in the Admin console, which lets it act on behalf of users in the domain.[1][5]
What Cotool uses from Google Workspace
- Audit logs
- Agents read Workspace audit logs during investigations, and Cotool has returned more complete audit results to response agents since release 0.70.0. Google's Reports API covers admin, Drive, login, mobile, and OAuth token activity.[1][6]
- OAuth token activity
- Token activity reports list events when users grant or revoke access for third-party apps, so agents can see every user who authorized an app and when.[7]
Response actions
These change state in Google Workspace, so they are the steps teams usually gate behind approval.
Detections, hunts, and triage
- Risky OAuth grantResponse
- Cotool's example OAuth Grant Responder lists the app's scopes and grants in Workspace, checks the publisher's domain in VirusTotal, traces what the token read and changed, and asks #security before revoking the app everywhere.[2]
- Session replay to DriveDetection
- A detection correlates Okta session replay with Google Workspace Drive audit events and runs every 15 minutes on both sources.[3]
- OAuth consent detectionsDetection
- Cotool's detection library includes a Google Workspace OAuth consent detection shown among its healthy detections.[3]
Example query
GET https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/token?eventName=revoke&maxResults=25Google's example request for OAuth token revoke events. Drop eventName to see grants too.[7]
Setup and permissions
Sign in to the Admin console as a super administrator, open domain-wide delegation, add the client ID, and enter the scopes. If a scope is missing later, edit the entry and add it; the client ID cannot be edited.[5]
| Permission | Access | Why |
|---|---|---|
https://www.googleapis.com/auth/admin.reports.audit.readonlyView audit reports for the Workspace domain.[8] | Read | View audit reports for the Workspace domain.[8] |
https://www.googleapis.com/auth/apps.alertsRead and write access to the Alert Center API.[10] | Write | Read and write access to the Alert Center API.[10] |
https://www.googleapis.com/auth/admin.directory.user.readonlyRetrieve users and aliases.[11] | Read | Retrieve users and aliases.[11] |
https://www.googleapis.com/auth/admin.directory.user.securityList and delete a user's OAuth tokens, app-specific passwords, and verification codes.[11][12] | Write | List and delete a user's OAuth tokens, app-specific passwords, and verification codes.[11][12] |
https://www.googleapis.com/auth/admin.directory.userAll user operations, needed for password resets. Leave it out for read-only use.[11] | Write | All user operations, needed for password resets. Leave it out for read-only use.[11] |
How Cotool works with Google Workspace
- Cotool's Google Admin integration has supported detection authoring since release 0.31.0, and later releases made Google Admin queries more reliable.[1]
FAQ
- Who has to set up domain-wide delegation?
- A Google Workspace super administrator. Google's steps for adding a client ID and scopes require that role.[5]
Sources
- Changelog (Cotool docs) · accessed November 16, 2026
- Respond to every signal (Cotool Respond) · accessed November 16, 2026
- Detections are code (Cotool Detect) · accessed November 16, 2026
- Observe (Cotool) · accessed November 16, 2026
- Control API access with domain-wide delegation (Google Workspace Admin Help) · accessed November 16, 2026
- Reports API overview (Google for Developers) · accessed November 16, 2026
- Reports API: OAuth token activity report (Google for Developers) · accessed November 16, 2026
- Choose Reports API scopes (Google for Developers) · accessed November 16, 2026
- Alert Center API overview (Google for Developers) · accessed November 16, 2026
- Choose Alert Center API scopes (Google for Developers) · accessed November 16, 2026
- Choose Directory API scopes (Google for Developers) · accessed November 16, 2026
- REST resource: tokens (Directory API) · accessed November 16, 2026
