Docs · Connect your tools
Connect Google Workspace
StackWeaver reads, and never changes, the user directory of your Google Workspace once a day, through one read-only permission. There are two ways to grant it: a super administrator approves on Google's own page, or pastes a service account key with domain-wide delegation. This guide says what is read, what each approval allows and how to remove it.
Last reviewed: 6 November 2026 · Describes what is live in production on that date. A result is evidence of what the provider returned at a time, nothing more.
1. What it collects
Once a day StackWeaver lists your users through the Admin SDK Directory API. Each result is kept as an Evidence Object with a SHA-256 fingerprint (platform), including results that fail. StackWeaver keeps counts and opaque Google user ids, and your Google customer id and primary domain. It does not keep names or e-mail addresses (what is stored).
| Check (as shown in the portal) | What it looks at |
|---|---|
| Active users enrolled in 2-step verification | How many active users are enrolled, and the ids of those who are not |
| 2-step verification enforced | Whether 2-step verification is enforced for each active user |
| Number of super administrators | How many active super administrators there are (more than five, or none, is shown as a failure: a StackWeaver threshold, not Google's) |
| Suspended and archived accounts | Counts of active, suspended and archived accounts. Evidence only, no threshold |
| Active users with no recent sign-in | Active users who have not signed in for 90 days or more, or never |
2. What it does not do
- It does not read Gmail, Drive, Calendar, groups or devices, and it cannot change anything in your Workspace.
- It does not store user names or e-mail addresses in the evidence.
- It does not say your domain meets any standard. A result is what Google returned at a certain time.
3. The access it needs
One permission: "See info about users on your domain", the Directory API scope admin.directory.user.readonly (Google). StackWeaver also asks for the openid and email sign-in claims, which tell it which account approved.
Who can connect. In StackWeaver, a workspace owner or admin either way. On Google's side, both paths need a super administrator of the Workspace: for the Connect button, StackWeaver asks Google, with the new approval, whether the person who approved is a super administrator, and refuses if not, reading the domain from the signed reply Google sends (Google), never from the address the browser returns to; a personal Google account is refused. For a service account key, a super administrator authorises the key's client ID for this one scope in the Admin console (Security, API controls, Domain-wide delegation), and the e-mail address pasted alongside the key must itself be a super administrator.
Unverified app warning (Connect button only). Google limits an app that asks for sensitive or restricted permissions and has not completed Google's verification to 100 new users in total, and shows an "unverified app" screen before the approval page (Google). Whether this permission counts as sensitive has not been confirmed. StackWeaver's Google app is not verified, and nothing here says it is. The service account path has no consent screen, so this does not apply to it.
4. Connect steps
Two ways to connect. Use whichever suits your situation — the service account path works even if the OAuth consent screen is awkward to complete (for example a Workspace that is not yet fully provisioned), since it has no browser sign-in step.
- Connect button. In StackWeaver, open Evidence, then the Google Workspace section, press Connect Google Workspace. Only a workspace owner or admin sees the button.
- Sign in to Google with a super administrator account of your Workspace. If Google shows an unverified app screen, that is expected while the app is unverified.
- Approve the one read-only permission. You come back to StackWeaver, which tests the connection and shows the result.
- Service account key. In Google's developer console, create a service account and a JSON key for it (IAM & Admin, Service Accounts, Keys, Add key).
- In the Workspace Admin console, open Security, API controls, Domain-wide delegation, and authorise that service account's client ID for the scope admin.directory.user.readonly.
- In StackWeaver, open Evidence, the Google Workspace section, and choose "Paste a service account key" instead of Connect. Enter the super administrator e-mail the key should act as, and paste the whole key file's JSON contents.
- Press Test connection. StackWeaver signs its own short-lived token with the key each time it reads your directory; nothing is typed again after this.
5. Reading the results
| Label | What it means |
|---|---|
| Pass | Google returned data that meets the threshold at that time |
| Fail | Google returned data that does not meet the threshold |
| Not enabled | There was nothing to check, for example no active users |
| Could not check | StackWeaver could not read the data, or the list was too large to read completely |
6. Disconnect and revoke
- In StackWeaver, press Disconnect on the Google Workspace section. StackWeaver deletes the stored approval tokens and asks Google to revoke the approval (Google).
- If Google could not be reached, the card says so. A super administrator can then remove StackWeaver from the list of third-party apps in the Admin console's API controls (Google's menu names can change), or the person who approved can remove it in their Google account's connected apps.
What remains. Past evidence stays in your workspace as the audit trail. Disconnecting does not delete it.
7. Troubleshooting
| Message | What to do |
|---|---|
| Only a super administrator of the Google Workspace can connect it | Sign in with a super administrator account and press Connect again |
| That Google account does not belong to a Google Workspace domain | Use your Workspace account, not a personal Gmail account |
| That account is already connected to another StackWeaver workspace | Ask StackWeaver support if this is your Workspace |
| The approval was declined, so nothing was connected | Press Connect again and approve the permission |
| Google would not let StackWeaver list users (service account key) | Check the Admin console's domain-wide delegation authorisation for the key's client ID and the scope, and that the e-mail given is a super administrator |
| <email> is not a super administrator of this Workspace | Paste the key again with a super administrator's e-mail address |
Still stuck? Use the contact page.
Sources and method
Statements about GitHub and Okta link to their own documentation. Statements about StackWeaver link to the page that says them, or are recorded in a claims ledger with the file in StackWeaver's repository that they come from. See oureditorial policy. Spotted an error? Use the contact page.