> For the complete documentation index, see [llms.txt](https://surecloud.gitbook.io/surecloud-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-cloud/google-workspace-audit-logs.md).
# google workspace audit logs
SureCloud connects to the Google Workspace Admin Reports API to collect audit log events across four key applications: Admin (administrative actions), Login (authentication events), Drive (file access and sharing), and Token (OAuth application authorisations). SureCloud uses these logs to provide evidence that administrative activity is captured, that authentication events are monitored, and that OAuth application grants are tracked and reviewed.
## Endpoints
| API Call | Use Case |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `GET /admin/reports/v1/activity/users/all/applications/admin` | Collect Admin activity events (user creation, role changes, policy updates) |
| `GET /admin/reports/v1/activity/users/all/applications/login` | Collect login events including failed logins, suspicious logins, and 2SV challenges |
| `GET /admin/reports/v1/activity/users/all/applications/drive` | Collect Drive events including external shares, permission changes, and file deletions |
| `GET /admin/reports/v1/activity/users/all/applications/token` | Collect OAuth token grant and revocation events |
| `GET /admin/reports/v1/activity/users/all/applications/mobile` | Collect mobile device management events (device enrolment, wipe, policy violations) |
## Pagination
The Reports API uses a `nextPageToken` field for paginated event responses. SureCloud passes the token as the `pageToken` query parameter until no token is returned.
```json
{
"kind": "admin#reports#activities",
"items": [
{
"id": { "time": "2025-06-01T10:00:00.000Z", "applicationName": "admin" },
"actor": { "email": "admin@yourcompany.com" },
"events": [ { "name": "CREATE_USER", "parameters": [ ... ] } ]
}
],
"nextPageToken": "A:1748779200000000:..."
}
```
{% hint style="info" %}
Google Workspace audit logs are retained for **6 months** (180 days) for most editions, and up to **1 year** on Enterprise editions. SureCloud collects events within a rolling window per polling cycle. Events older than the retention window cannot be retrieved from the Reports API.
{% endhint %}
## Required permissions
The service account must have domain-wide delegation granted for the following scope:
| OAuth scope | Purpose |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `https://www.googleapis.com/auth/admin.reports.audit.readonly` | Read all audit log applications via the Reports API |
| `https://www.googleapis.com/auth/admin.reports.usage.readonly` | Read usage reports (for aggregate MFA and device coverage metrics) |
The impersonated admin account must have the **Reports** admin privilege to access audit log data across all users in the domain.
## Troubleshooting
Admin or Login audit events are returning empty
The `admin.reports.audit.readonly` scope must be listed in the domain-wide delegation entry and the impersonated admin account must have the **Reports** privilege.
In the Admin Console, navigate to **Security → API controls → Manage domain-wide delegation**, click **Edit** on the SureCloud entry, and confirm the full scope URL `https://www.googleapis.com/auth/admin.reports.audit.readonly` is present.
Also confirm the impersonated account has **Reports** under its admin role privileges at **Account → Admin roles → \[Role] → Privileges → Reports**.
Drive audit events appear with a delay
Drive audit log events can take up to 2 hours to appear in the Reports API after the activity occurs. SureCloud's default Drive audit polling interval is 6 hours to account for this delay. Events within the last 6 hours may not yet be visible at the time of a given collection run — they will be collected on the subsequent cycle.
Token audit events are missing for some OAuth authorisations
The Token audit log records OAuth 2.0 application authorisation grants and revocations. If a token grant occurred before SureCloud was connected, or before the `admin.reports.audit.readonly` scope was granted, those historical events may be within the retention window but outside SureCloud's first collection point.
SureCloud collects token events from the point the integration was first connected. Historical events from before the connection date will not be backfilled.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/google-cloud/google-workspace-audit-logs.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.