Connect Google Workspace
Google Workspace is the identity layer for the businesses that run on it — every user account, every group, every managed Chromebook and every mailbox setting lives there. StackJack connects to it…
Written By Christopher Scaminaci
Last updated 6 days ago
Google Workspace is the identity layer for the businesses that run on it — every user account, every group, every managed Chromebook and every mailbox setting lives there. StackJack connects to it through Google's official administration APIs, so your AI can answer questions about a customer's Workspace domain and make changes to it without anyone opening the Admin console.
Connecting Google Workspace gives your AI a set of gws_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:
- Look up users, list who belongs to a group, and check whether someone has access
- Create, suspend, restore and delete user accounts, and move people between organizational units
- Manage groups, group aliases, membership and posting policy, including nested groups
- Build and reorganize the organizational unit tree that policy is applied to
- Manage enrolled Chromebooks and mobile devices, including remote commands and wipes
- Audit who holds administrator roles, and who granted them
- Investigate account security — the third-party apps a person has authorized, their app passwords, and their 2-step verification state
- Read the audit log and the usage reports behind questions like "who has not signed in for months?"
- Manage mail domains, domain aliases, meeting rooms, licence assignments and shared drives
- Work with Vault matters, legal holds and exports, and with managed-Chrome policy
- Administer an individual mailbox's settings — forwarding, delegates, filters, send-as addresses, vacation replies, IMAP and POP, and S/MIME or client-side-encryption certificates
Grant one or more of the optional permission groups in step 5 and the same connection also reaches:
- Reseller and Cloud Channel — the subscriptions, customers, entitlements, offers and billing surfaces you sell Google Workspace through, if you are a Google partner
- Cloud Identity — dynamic and security groups, device and device-user inventory, SAML and OIDC single sign-on profiles, and organization policies
- Chrome Management — browser and ChromeOS telemetry, installed-app and extension inventory, managed Chrome profiles and security-insight reports
- Mail content — reading, searching, sending, importing and labelling a named person's mail, and downloading its attachments
- Drive files — a named person's files and folders, sharing and permissions, comments and revisions, and downloading or exporting file contents
- Calendar — a named person's calendars, events, sharing rules and free/busy lookups
- Contacts — a named person's contacts and contact groups, plus Workspace directory search
- Tasks, Chat, Meet and Keep — task lists and tasks; Chat spaces, membership, messages, reactions and pins; meeting spaces, conference records, participants, recordings and transcripts; and Keep notes with their sharing and attachments
That mailbox-settings group is worth calling out for security work. Four of those reads together answer "has this mailbox been tampered with?" — auto-forwarding, registered forwarding addresses, filters, and delegates. They are the four places an intruder sets up to keep reading someone's mail after the password has been changed, they are all available on the Free tier, and checking them by hand across a domain is exactly the tedious work an AI assistant is good at.
The full inventory, with the plan each tool needs, is in the tool reference.
What you will need
- A Google Cloud project you are willing to use for automation
- A super-administrator account in the Workspace domain
- About fifteen minutes, split across two different Google consoles
The setup is a little longer than most connectors because Google deliberately separates the two halves: you create the automation identity in one console, then authorize it in the other. Both halves are required, and a connector that has only the first will save successfully and then fail every request.
How the connection works
Rather than storing an administrator's password, StackJack uses a service account with domain-wide delegation. A service account is a non-human identity you create in Google Cloud. Domain-wide delegation is the permission, granted separately in the Admin console, that lets that identity act as one of your administrators.
Two consequences are worth knowing up front:
- StackJack acts as a person. You nominate a super-administrator for it to act as, and that person is who appears as the actor in your Google audit log. Their password is never used and nothing is ever sent to them. A dedicated automation admin who will not be offboarded is the tidiest choice.
- Access is granted in groups, and each group is all or nothing. Google matches the granted permissions exactly. Step 5 gives you one required block and several optional ones; if an entry is missing from a block, every tool that block unlocks fails with the same error, not just the ones needing it — while the other blocks carry on working. This is the single most common reason a setup does not work.
- You can come back and add a group later. Nothing already working breaks when you paste another block, and nothing needs re-entering in StackJack. Start with the required block and add what you need.
Setup
1. Create a Google Cloud project
Sign in to the Google Cloud console with an account in the same organization as the Workspace domain, and create a project — or pick an existing one you are happy to use for automation.
2. Enable the APIs
In APIs & Services → Library, enable each of these. They cover the core administration tools every connection gets:
Admin SDK API · Gmail API · Google Drive API · Google Vault API · Google Workspace Alert Center API · Chrome Policy API · Enterprise License Manager API · Groups Settings API · Data Transfer API
Enable these ten as well if you want any of the optional permission groups from step 5:
Google Workspace Reseller API · Cloud Channel API · Cloud Identity API · Chrome Management API · Google Calendar API · People API · Google Tasks API · Google Chat API · Google Meet API · Google Keep API
The mail-content and Drive-file tools need nothing extra here — they use the Gmail API and Google Drive API already in the first list.
Enable everything you might want now even if you only plan to use some. An API you skipped returns an error that reads like a permissions problem, and tracking that back to a switch you never flipped is a frustrating half hour.
3. Create a service account and download its key
In APIs & Services → Credentials, choose Create Credentials → Service account and give it a name that identifies StackJack.
Open the new service account, go to its Keys tab, and choose Add Key → Create new key → JSON. The file downloads once and cannot be downloaded again — treat it like a password.
4. Copy the numeric Client ID
Still on the service account, open the Details tab and copy the Client ID — the long number, not the email address.
This trips up more setups than anything else. The next step asks for the number; pasting the email there produces a connector that saves cleanly and then fails every call with an error that says nothing about which value was wrong.
5. Authorize it in the Admin console
In the Google Admin console, go to Security → Access and data control → API controls → Domain-wide delegation and choose Add new.
Paste the numeric Client ID from step 4, then paste the whole required list below into the OAuth scopes box in one go:
https://www.googleapis.com/auth/admin.directory.user,
https://www.googleapis.com/auth/admin.directory.user.alias,
https://www.googleapis.com/auth/admin.directory.user.security,
https://www.googleapis.com/auth/admin.directory.userschema,
https://www.googleapis.com/auth/admin.directory.group,
https://www.googleapis.com/auth/admin.directory.group.member,
https://www.googleapis.com/auth/admin.directory.orgunit,
https://www.googleapis.com/auth/admin.directory.device.chromeos,
https://www.googleapis.com/auth/admin.directory.device.mobile,
https://www.googleapis.com/auth/admin.directory.device.mobile.action,
https://www.googleapis.com/auth/admin.directory.domain,
https://www.googleapis.com/auth/admin.directory.rolemanagement,
https://www.googleapis.com/auth/admin.directory.resource.calendar,
https://www.googleapis.com/auth/admin.directory.customer,
https://www.googleapis.com/auth/admin.reports.audit.readonly,
https://www.googleapis.com/auth/admin.reports.usage.readonly,
https://www.googleapis.com/auth/apps.groups.settings,
https://www.googleapis.com/auth/apps.licensing,
https://www.googleapis.com/auth/apps.alerts,
https://www.googleapis.com/auth/admin.datatransfer,
https://www.googleapis.com/auth/ediscovery,
https://www.googleapis.com/auth/chrome.management.policy,
https://www.googleapis.com/auth/gmail.settings.basic,
https://www.googleapis.com/auth/gmail.settings.sharing,
https://www.googleapis.com/auth/drive
Paste that list complete. Trimming it to only what you think you need is the mistake this page warns about twice, because the failure it causes looks like a broken credential rather than a missing permission.
Optional scope groups
Everything above is required. Each block below is optional and unlocks one more family of tools. Paste a block into the same OAuth scopes box only if you want those tools — and paste it whole, because Google grants each block all or nothing. Leaving a block out costs you nothing else; the tools it would have unlocked simply report that the permission was not granted.
Adding a block later is a change in the Admin console only. Nothing in StackJack needs re-entering, and nothing already working stops.
Reseller and Cloud Channel — the subscriptions, customers, entitlements, offers and billing surfaces a Google partner sells through. See the If you are a Google reseller section further down this page; on a connection that is not a reseller's, this block grants nothing usable.
https://www.googleapis.com/auth/apps.order,
https://www.googleapis.com/auth/apps.reports.usage.readonly
Cloud Identity — dynamic and security groups, device and device-user inventory, SAML and OIDC single sign-on profiles, organization policies, and user invitations.
https://www.googleapis.com/auth/cloud-identity.groups,
https://www.googleapis.com/auth/cloud-identity.devices,
https://www.googleapis.com/auth/cloud-identity.devices.lookup,
https://www.googleapis.com/auth/cloud-identity.inboundsso,
https://www.googleapis.com/auth/cloud-identity.policies,
https://www.googleapis.com/auth/cloud-identity.allowlisteddomains,
https://www.googleapis.com/auth/cloud-identity.userinvitations
Chrome Management — browser and ChromeOS telemetry, installed-app and extension inventory, managed Chrome profiles, security-insight reports, and the connector configurations that feed Chrome security events to a third-party tool.
https://www.googleapis.com/auth/chrome.management.reports.readonly,
https://www.googleapis.com/auth/chrome.management.telemetry.readonly,
https://www.googleapis.com/auth/chrome.management.appdetails.readonly,
https://www.googleapis.com/auth/chrome.management.profiles,
https://www.googleapis.com/auth/chrome.management.securityinsights,
https://www.googleapis.com/auth/chrome.management.connectors
Mail content — reading, searching, sending, importing and labelling a named person's mail, and downloading its attachments. This is the one block that reaches your customers' actual email. Grant it deliberately, and read the note at the end of this page first.
https://mail.google.com/
Calendar — a named person's calendars, events, sharing rules and free/busy lookups.
https://www.googleapis.com/auth/calendar
People and contacts — a named person's contacts and contact groups, plus Workspace directory search.
https://www.googleapis.com/auth/contacts,
https://www.googleapis.com/auth/contacts.other.readonly,
https://www.googleapis.com/auth/directory.readonly
Tasks — a named person's task lists and tasks.
https://www.googleapis.com/auth/tasks
Google Chat — spaces, membership, messages, reactions and pins, plus each person's own Chat state. The three admin entries at the end are what let space and message search run across the domain.
https://www.googleapis.com/auth/chat.spaces,
https://www.googleapis.com/auth/chat.memberships,
https://www.googleapis.com/auth/chat.messages,
https://www.googleapis.com/auth/chat.messages.reactions,
https://www.googleapis.com/auth/chat.customemojis,
https://www.googleapis.com/auth/chat.users.readstate,
https://www.googleapis.com/auth/chat.users.spacesettings,
https://www.googleapis.com/auth/chat.users.availability,
https://www.googleapis.com/auth/chat.users.sections,
https://www.googleapis.com/auth/chat.spaces.pins,
https://www.googleapis.com/auth/chat.delete,
https://www.googleapis.com/auth/chat.admin.spaces,
https://www.googleapis.com/auth/chat.admin.memberships,
https://www.googleapis.com/auth/chat.admin.delete
Google Meet — meeting spaces, conference records, participants, recordings and transcripts.
https://www.googleapis.com/auth/meetings.space.created,
https://www.googleapis.com/auth/meetings.space.readonly,
https://www.googleapis.com/auth/meetings.space.settings
Google Keep — a named person's notes, their sharing and their attachments. Google restricts the Keep API to Workspace administrators.
https://www.googleapis.com/auth/keep
Drive apps — one tool, gws_list_drive_apps, which lists the third-party apps a person has connected to their own Drive. Google accepts a single scope on that one route and it is not in the required list, which is why it has a block of its own. Everything else about Drive, including reading one connected app by its ID, works without this.
https://www.googleapis.com/auth/drive.apps.readonly
Drive files needs no block. Access to Drive is already in the required list at the top of this step, so the file tools — including downloading and exporting file contents — work on any connection without anything being added here. The Drive apps block just above is the one exception, and it covers a single tool.
6. Enter the details in StackJack
Open the downloaded JSON key file in a text editor and copy two values out of it:
The private key is a long, multi-line block. If you copy it straight out of the JSON file, the line breaks appear as the two characters \n — paste it that way anyway, StackJack handles it.
Google's endpoints are global and fixed, so there is no URL to enter.
If you are a Google reseller
Skip this section unless you resell Google Workspace.
A reseller connection is an ordinary connection with one difference: the service account lives in your own Workspace, and the administrator you nominate in step 6 is an administrator of your reseller Workspace who has access to the Partner Sales Console. A customer's own super-administrator will not do — Google refuses the reseller permissions for them, and the failure looks exactly like a missing scope.
Set one up like this:
- Follow the setup above in your own Workspace domain, not a customer's.
- In step 5, paste the Reseller and Cloud Channel block alongside the required list.
- In step 6, fill in the Cloud Channel account ID field with the account number shown in your Partner Sales Console. Google publishes that number nowhere an integration can read it, so the Cloud Channel tools stop and tell you rather than guessing. The Reseller tools do not need it.
Reaching a resold customer
Once that connection exists, the customer-scoped administration tools take an optional customerId — your resold customer's numeric Google customer ID. Pass it and the tool acts on that customer's domain for that one call; leave it out and the tool acts on your own domain. That covers users, groups, org units, devices, domains, roles, custom fields, reports, licences, Chrome policy, alerts, data transfers, calendar resources (meeting rooms and buildings), Cloud Identity and Chrome Management.
Mailboxes and files are the exception, and it is not a small one. Mail, Drive file, calendar, contact, task, chat, meet and keep tools act on one named person's data, and Google will only let a service account act as a person if that service account has been authorized inside that person's own domain. A reseller connection cannot reach them however the customerId is set.
So, for every customer whose mailboxes or files you manage, add a connection per customer (Connectors → Google Workspace → Add connection). Each one is the setup above, run in that customer's Admin console. You can reuse the same service-account key file across them or use a separate one per customer — Google's domain-wide delegation is granted per domain either way.
What your plan includes
The access granted in step 5 is read-and-write even on the Free tier. That is deliberate: re-granting delegation later would mean another manual trip to the Admin console when you upgrade. Your StackJack plan is what restricts a Free connection to read-only tools.
Tools that change things
Some tools make changes that are hard or impossible to undo. These require the Pro tier and are marked destructive. Whether your AI application asks you to confirm before running one depends on that application's own settings — see Destructive tools and confirmation. Review those settings, and grant only what you want an AI to reach:
- Deleting a user. Google keeps the account restorable for 20 days, then it is gone. Transfer their Drive and Calendar data first — deleting does not reassign it. If the intent is simply to block access, suspending the account is instantly reversible and keeps everything.
- Deleting a group. Unlike a user, a deleted group has no restore window. Its archived conversations are destroyed, its address starts bouncing, and every permission granted through it disappears — which can silently remove access for everyone who held it that way.
- Granting super-administrator. This hands an account total control of the domain.
- Signing a user out everywhere. Every session on every device ends immediately, including phones.
- Removing someone from a group. Treat this as an access revocation, not a mailing-list edit: they lose the shared drives, calendars and documents the group granted.
- Wiping a device. For a phone there are two wipes and they are very different: one removes only the work account and its data, the other factory-resets the whole handset including the owner's personal photos and apps. For a Chromebook, deprovisioning cannot be undone through the API — the hardware has to be wiped and re-enrolled by hand.
- Releasing a legal hold in Vault. Once a hold is released, the data it was preserving can be deleted if nothing else is preserving it. This is a decision for whoever owns the legal obligation, not a tidy-up.
- Revoking a licence. The person loses the paid service. For the main Workspace licence that means losing access to their own mail and Drive, while the account still exists.
- Assigning a licence. This one adds rather than removes, but it puts a charge on the customer's next Google bill, so it carries the same marking.
- Removing a managed network or certificate from Chrome devices. Devices relying on it lose their connection or start showing certificate warnings — and a device that cannot connect cannot be fixed remotely.
- Deleting a shared drive. By default Google refuses to delete a drive that still contains files. There is an option to override that and delete the contents too; it removes an entire team's documents in one step.
- Turning on mail forwarding, or adding a forwarding address. Forwarding sends a copy of every incoming message to another address. It is a legitimate feature and it is also the most common way an intruder keeps reading a mailbox after being locked out, so both halves carry the marking. Turning forwarding off uses the same tool, and is the usual response when you find it switched on unexpectedly.
- Adding a delegate to a mailbox. A delegate can read, search and send as the mailbox owner. Confirm the owner actually asked for it.
- Creating a mail filter. A filter acts automatically on mail arriving from then on, and it can be set to delete or hide matching messages without telling the owner. Deleting a filter carries the same marking, because its rules cannot be recovered.
- Adding or verifying a send-as address. If the address is outside the domain, Google immediately emails a verification message to whoever owns it. That cannot be recalled, and running the tool again sends again.
- Turning on a vacation auto-reply. The text you set is sent automatically to everyone who writes in, including people outside the organization.
- Disabling a client-side-encryption key pair. Mail already encrypted with that key stops being readable until it is switched back on. Move the user to a different key first.
The optional groups add more of the same kind:
- Anything that changes a resold customer's subscription or entitlement. Creating, changing, suspending, activating, transferring or cancelling a subscription, and every repricing change, moves money on your Google bill and theirs. Every one of them carries the same marking.
- Deleting mail, files, calendars, events, contacts, Chat messages, Chat spaces or Keep notes. Where Google's delete skips the trash the removal is permanent, and the tool description says so; where a trash exists, the trash tool is the reversible one to reach for.
- Sending a message. Sending mail or posting a Chat message reaches a human immediately and cannot be recalled.
- Anything that emails or notifies people. Calendar event writes can email every attendee; the tools default that off, and say so when a non-default value turns it back on. Sharing a file, a calendar or a Keep note grants someone access — treat those as access grants, not tidy-ups.
- Ending an active Meet conference. Everyone in the meeting is disconnected at once.
You will also notice pairs of tools that look similar — one named Replace and one named Update Fields. The Replace variants overwrite the entire record, clearing anything not included, which is why they are marked as changing things. The Update Fields variants change only what you name and leave the rest alone. For everyday edits, the Update Fields tool is the one you want.
See the generated Google Workspace tool reference for the current inventory, plan assignment, input schemas, and destructive-action labels.
Troubleshooting
"Google refused the delegation" / unauthorized_client Almost always step 4 or step 5. Either the domain-wide delegation entry has the service account's email address instead of its numeric Client ID, or the permission list is incomplete. Re-open Security → Access and data control → API controls → Domain-wide delegation, check the Client ID matches the number on the service account's Details tab, and re-paste the whole list from step 5.
One area fails and everything else works That is the per-group grant doing its job: the block covering that area is missing or incomplete. The error message names the group and the exact permissions to paste. Re-paste that block whole — a block granted partially fails the same way as one not granted at all.
"This needs your Cloud Channel account ID" Only the Cloud Channel tools ask for it, and only a reseller has one. Copy the account number from your Partner Sales Console into the Cloud Channel account ID field in step 6. There is nothing to fall back on: Google does not publish that number anywhere an integration can read it.
A reseller connection cannot open a resold customer's mailbox or files Expected. Passing customerId reaches that customer's directory, not their people's data — Google requires the service account to be authorized inside the customer's own domain for that. Add a connection for that customer, following the setup above in their Admin console.
"Google rejected the administrator account" / invalid_grant The address you entered does not exist in the domain, is suspended, or is no longer a super-administrator. Check it in the Admin console and re-enter it in StackJack if it changed.
"The Google API this tool needs is not switched on" Go back to step 2 and enable the API named in the error. This reads like a permissions problem but is not.
"Google accepted the connection but refused this operation" The connection is fine, so this is about reach. Most often the account you nominated is not a full super-administrator and lacks the privilege that area needs. Check its role in the Admin console first.
"Google is rate-limiting requests" Two different limits produce this, and only one is yours to change. If the message mentions your project's quota, you can raise it in the Google Cloud console under IAM & Admin → Quotas. If it mentions your Workspace account, that limit is fixed by Google and cannot be raised — spread bulk work out rather than running wide sweeps back to back. Either way StackJack paces requests and backs off on its own, so no action is usually needed.
Reports look empty or out of date Google's audit and usage data lags behind real time — commonly by hours, and for some reports by up to three days. A report that does not yet show something you know happened is usually too early rather than wrong.
Mail and file contents
This connector can now read mail messages and file contents, and the two are reached differently.
Mail content needs its own permission. Reading, searching or sending someone's mail requires the Mail content block from step 5, which no existing connection has until you paste it. There is no way to reach a message without it, and there is no tool that reads mail across the domain in one call: every mail-content tool names the mailbox owner explicitly and acts as that person.
File content needs nothing added. Access to Drive has been in the required list since this connector shipped, so the file tools — including downloading and exporting a file's contents — work on every existing connection from the moment they appear. If that is more than you want an AI assistant reaching, restrict it in StackJack rather than in Google. Which control does it depends on how the connection is made: for an endpoint's own credentials it is that endpoint's tool selection, and for someone signed in through StackJack it is the tool role on their membership.
Either way, your Google audit log records the administrator you nominated in step 6 as the actor, not StackJack and not the mailbox or file owner. That is how domain-wide delegation works everywhere, and it is why a dedicated automation admin — rather than a real person's account — is worth the five minutes it takes to create.
Several customers
Some MSPs need one Google Workspace connection per customer, console or region. StackJack can hold several named connections of one connector, and your AI names the one it wants on each call. See Several connections of one connector.
What is not included
One capability is held back on purpose. Google offers a way to permanently destroy a client-side-encryption key pair, which makes every message ever encrypted with it unreadable forever, with no undo and no support path. StackJack does not expose it. Disabling a key pair — which is reversible — is as far as the connector goes; permanent destruction stays a deliberate, human action in the Admin console.
Uploading file contents is not supported. The connector can create a file, a folder or an empty Doc or Sheet, rename it, move it, share it, trash it and read or export what is in it — but it cannot push bytes up. Google requires a different kind of request for that than this connector makes, so a file's contents are set in Drive itself.
Context-Aware Access is out of scope. Its rules live in the Google Cloud organization rather than in Workspace and need a different kind of credential entirely, so no tool here reads or changes them.
Google Workspace tools
gws_ · 652 tools · Free 303 · Pro 349
Users
Groups
Group Members
Organizational Units
ChromeOS Devices
Mobile Devices
Domains
Chrome Policy
Vault
Licences
Alert Center
Reports
Group Settings
Data Transfer
Calendar Resources
Custom User Schemas
Account Security
Admin Roles
Customer
Shared Drives
Gmail Settings
Reseller
Cloud Channel
Cloud Identity
Chrome Management
Gmail content
Drive files
Calendar
People
Tasks
Chat
Meet
Keep
More in Connector guides
Connect Acronis Cyber Protect CloudConnect Action1Connect AddigyConnect AlertOpsStill need help? Ask the team