[Google Workspace] Create a user. Additive — it creates a new account and changes nothing existing. Required body fields are primaryEmail, name.givenName, name.familyName and password. Example: {"primaryEmail":"jsmith@example.com","name":{"givenName":"Jane","familyName":"Smith"},"password":"a-strong-password","changePasswordAtNextLogin":true,"orgUnitPath":"/Sales"}. NOTE: creating a user normally consumes a licence and therefore affects the customer's bill. Google rate-limits user creation to about 10 per domain per second.

[Google Workspace] Add an alias address to a user. Additive — mail to the alias arrives in the same mailbox and the primary address is unaffected. The alias domain must already be registered with the Workspace account (see gws_list_domains). Aliases can take up to 24 hours to begin receiving mail.

[Google Workspace] Delete a user account. The account stops working immediately and its Gmail, Drive and Calendar data become inaccessible. Google keeps it restorable via gws_undelete_user for 20 days, after which it is gone permanently. Consider two things first: transfer the user's Drive and Calendar data with gws_create_data_transfer, since deletion does NOT reassign it; and prefer SUSPENDING the account (gws_patch_user with {"suspended":true}) if the intent is to block access rather than to remove the person, because suspension is instantly reversible and preserves everything.

[Google Workspace] Remove an alias address from a user. Destructive: mail sent to that address stops being delivered immediately and bounces, which silently breaks anything still addressing the old alias — mailing lists, saved contacts, external systems. The primary address and the mailbox itself are unaffected.

[Google Workspace] Remove a user's profile photo, reverting them to the default placeholder. Destructive: the stored image is gone and cannot be recovered through the API — re-setting one means uploading the original file again.

[Google Workspace] Retrieve one user. userKey accepts the primary email address, any alias address, or the numeric user id — all three resolve. Use projection FULL to include custom schema fields, or CUSTOM with customFieldMask to include only named schemas. The response carries the user's org unit path, admin status, suspension state, last login, and 2-step verification enrolment.

[Google Workspace] Retrieve a user's profile photo. The image comes back as web-safe base64 in the photoData field, along with its dimensions and mime type. A user who has never set a photo returns 404 rather than an empty result.

[Google Workspace] List a user's alias email addresses — additional addresses that deliver to the same mailbox. Unpaginated: Google always returns the complete set, so there is no page token. When the user has no aliases the aliases key is omitted entirely rather than returned empty.

[Google Workspace] List users in the Workspace account. Paginates with pageToken/nextPageToken; maxResults caps at 500 and is clamped there. Scope defaults to the whole customer — pass domain only to narrow to one domain of a multi-domain customer (domain and customer are mutually exclusive upstream, so StackJack sends whichever applies). The query parameter takes Google's user search syntax, e.g. "isAdmin=true", "orgUnitPath='/Sales'", "email:jsmith*", or "isSuspended=true". Set showDeleted to "true" to list recently deleted users instead of active ones (they remain restorable for 20 days). NOTE: when no user matches, Google OMITS the users key entirely rather than returning an empty array.

[Google Workspace] Grant or revoke SUPER-ADMINISTRATOR status. Destructive in the security sense: granting it hands the account total control of the domain — every user, every device, all mail and all files — and revoking it can lock an administrator out of work they are mid-way through. Nothing is deleted either way. Pass status=true to grant, false to revoke. For anything narrower than full control, assign a specific admin role with gws_assign_role instead.

[Google Workspace] Update named fields on a user, merging rather than replacing — omitted fields are left alone. This is the tool to use for almost every user edit. Suspend with {"suspended":true} and restore with {"suspended":false}; move org unit with {"orgUnitPath":"/Sales/West"}; rename with {"name":{"givenName":"Jane","familyName":"Doe"}}; force a password reset with {"changePasswordAtNextLogin":true}. Suspending is the reversible alternative to deletion and is what offboarding usually wants: it blocks sign-in immediately while preserving the account and its data.

[Google Workspace] Invalidate EVERY active web and device session for a user, signing them out everywhere at once. Destructive: the person loses unsaved work in open sessions and must re-authenticate on every device, including phones. This is a standard containment step for a suspected account compromise — pair it with a password reset (gws_patch_user with {"password":"...","changePasswordAtNextLogin":true}), since signing out alone does not stop someone who knows the password from signing straight back in.

[Google Workspace] Restore a user deleted within the last 20 days. Restorative, not destructive. IMPORTANT: this takes the NUMERIC user id, not the email address — find it with gws_list_users passing showDeleted="true". Optionally place the restored user in a specific org unit; the default is the root org unit "/".

[Google Workspace] REPLACE a user's record wholesale. This is Google's PUT: any field you omit is CLEARED and any list you omit is emptied, so sending a partial body silently erases phone numbers, addresses, custom schema values and more. Prefer gws_patch_user for ordinary edits — it merges instead, and is the right tool for suspending a user ({"suspended":true}), moving them between org units, or changing a single field.

[Google Workspace] Set a user's profile photo. Reversible — setting a new photo simply replaces the previous one, and the change affects only the picture. photoData must be WEB-SAFE base64 (the standard + and / characters replaced with - and _), which is not the same as ordinary base64. Example: {"photoData":"_9j_4AAQSkZJRg...","mimeType":"JPEG"}.

[Google Workspace] Create a group. Additive — nothing existing changes. Only email is required: {"email":"sales@example.com","name":"Sales Team","description":"Regional sales"}. The new group starts empty; add people with gws_add_group_member. A newly created group takes Google's default access settings, so adjust posting and visibility policy with gws_update_group_settings if the defaults are not what you want.

[Google Workspace] Add an alias address to a group. Additive — mail to the alias reaches the same group and the primary address keeps working. The alias domain must already be registered with the Workspace account. Useful for retiring an old address gracefully: rename the group, then add the former address as an alias so nothing bounces.

[Google Workspace] Delete a group. Destructive and NOT recoverable through the API — unlike a deleted user, a deleted group has no 20-day restore window. Its archived conversations are destroyed, its address stops accepting mail and bounces, and every permission granted TO the group (shared drives, calendars, documents) is lost, which can silently remove access for everyone who held it through that group. Members' own accounts are unaffected.

[Google Workspace] Remove an alias address from a group. Destructive: mail to that address stops being delivered immediately and bounces, breaking anything still addressing it. The group's primary address is unaffected.

[Google Workspace] Retrieve one group. groupKey accepts the group's email address, an alias address, or its numeric id. The response carries the name, description, direct member count and aliases. For the group's POSTING and MODERATION policy — who may post, who may view members, whether external senders are allowed — use gws_get_group_settings instead; that lives in a separate Google API and is not part of this response.

[Google Workspace] List a group's alias addresses — additional addresses that deliver to the same group. Unpaginated: Google returns the complete set. When the group has no aliases the aliases key is omitted entirely.

[Google Workspace] List groups. Paginates with pageToken/nextPageToken; maxResults caps at 200 (NOT 500 — the group cap is lower than the user cap) and is clamped there. Three mutually exclusive scoping modes: pass userKey to list only the groups one person belongs to (the narrowest, and what "which groups is Jane in?" wants), pass domain to narrow to one domain, or pass neither for the whole customer. StackJack sends whichever applies, since Google rejects more than one. When nothing matches, the groups key is omitted entirely rather than returned empty.

[Google Workspace] Update named fields on a group, merging rather than replacing — omitted fields are left alone. The right tool for renaming a group ({"name":"Sales EMEA"}) or editing its description. Changing the email address here also renames the group's address, and mail to the old one stops arriving unless you keep it as an alias.

[Google Workspace] REPLACE a group's record wholesale. Google's PUT: omitted fields are CLEARED, so a body carrying only a new name will also wipe the description. Prefer gws_patch_group for ordinary edits. Membership is NOT affected by either tool — it lives on its own endpoints.

[Google Workspace] Add a member to a group. Additive. Body: {"email":"jsmith@example.com","role":"MEMBER"} — role is MEMBER (default), MANAGER or OWNER. The email may name a user, another group (creating a nested membership), or an external address if the group's settings allow outside members. Adding someone GRANTS them everything the group grants: shared drives, calendars and documents shared with it, so treat a group add as an access grant rather than a mailing-list change.

[Google Workspace] Answer whether a user is a member of a group, returning {"isMember":true|false}. Unlike gws_get_group_member this DOES follow nested groups, so it answers the effective-access question — "can this person reach what the group grants?" — rather than the direct-membership one. The cheapest way to check one person against one group; use gws_list_group_members when you need the whole roster.

[Google Workspace] Retrieve one membership record, carrying the member's role (OWNER, MANAGER or MEMBER), type (USER, GROUP, CUSTOMER or EXTERNAL) and mail delivery preference. Returns 404 when the member belongs only INDIRECTLY through a nested group — use gws_check_group_membership if the question is simply whether someone is effectively a member.

[Google Workspace] List a group's members. Paginates with pageToken/nextPageToken; maxResults caps at 200 and is clamped there. By DEFAULT this returns only DIRECT members — a person who belongs through a nested group does NOT appear. Pass includeDerivedMembership=true to expand nested groups and see everyone who actually receives the group's mail, which is usually what an access review wants. Filter by role with roles="OWNER,MANAGER" (comma-separated, no spaces). When the group is empty the members key is omitted entirely rather than returned empty.

[Google Workspace] Update named fields on a membership, merging rather than replacing. The right tool for promoting or demoting someone: {"role":"MANAGER"}. Omitted fields are left alone.

[Google Workspace] Remove a member from a group. Destructive as an ACCESS REVOCATION: the person immediately loses everything the group granted — shared drives, calendars and documents shared with it — and stops receiving its mail. Their own account and files are untouched. The change takes effect at once and is undone only by adding them back, which does not restore anything they created under the group's access in the meantime.

[Google Workspace] REPLACE a membership record wholesale. Google's PUT: fields omitted from the body are cleared, so a body carrying only a role also resets the member's mail delivery preference. Prefer gws_patch_group_member for ordinary role changes. Note that demoting the last OWNER can leave a group with nobody able to administer it from the Groups interface.

[Google Workspace] Create an organizational unit. Additive — the new unit starts empty and inherits its parent's settings. Body: {"name":"West","parentOrgUnitPath":"/Sales","description":"Western region"}. Google rate-limits org unit creation to about one per customer per second, so create them one at a time rather than in a burst.

[Google Workspace] Delete an organizational unit. Destructive: every policy configured on it is lost and is not recoverable through the API. Google refuses to delete a unit that still contains users, devices or child units, so move those out first — and note that moving users into the parent silently re-applies the PARENT's policy to them, which may loosen restrictions the deleted unit was enforcing. Check what the unit contains with gws_list_users (query "orgUnitPath='/Path'") before deleting.

[Google Workspace] Retrieve one organizational unit by its full path, e.g. "/Sales/West". Pass the path with its slashes exactly as shown — do not URL-encode them. The response carries the unit's name, description, parent path and whether it blocks inheritance of parent settings.

[Google Workspace] List organizational units. UNPAGINATED — Google always returns the full result set, so there is no page token and no page size. By default this lists the CHILDREN of the root; pass orgUnitPath to list beneath a different node, and type="all" to return the whole subtree rather than just immediate children. Org units are how Workspace scopes policy, so this is the map to read before changing any setting that applies to a subset of users.

[Google Workspace] Update named fields on an organizational unit, merging rather than replacing. The right tool for renaming ({"name":"West Region"}) or editing a description. Be aware that setting {"blockInheritance":true} stops the unit inheriting parent policy, which changes the effective settings for everyone in it.

[Google Workspace] REPLACE an organizational unit's record wholesale. Google's PUT: omitted fields are cleared. Prefer gws_patch_org_unit for ordinary edits. Changing parentOrgUnitPath MOVES the unit and everything beneath it, which re-applies whatever policy the new parent carries to every user and device inside — a change that can be far larger than it looks.

[Google Workspace] Change the enrollment status of a batch of ChromeOS devices. DEPROVISION IS IRREVERSIBLE through the API: a deprovisioned device releases its licence, stops receiving policy, and can only be re-enrolled by physically wiping and re-enrolling the hardware — for some licence types that requires a new licence. DISABLE is the recoverable option for a lost or stolen device: it locks the device and shows a message, and REENABLE undoes it. Body: {"deviceIds":["..."],"changeChromeOsDeviceStatusAction":"CHANGE_CHROME_OS_DEVICE_STATUS_ACTION_DISABLE"}; deprovisioning also requires a deprovisionReason. Confirm which devices are in the list before running this.

[Google Workspace] Count ChromeOS devices without listing them. Returns a SINGLE total — {"count":"142"} — for the devices matching the request, not a breakdown by status; to count each status, call this once per status with filter="status:provisioned" and so on. The cheap way to size a fleet, since it costs one call where paging the list costs dozens. NOTE the org-unit form: Google documents orgUnitPath here WITHOUT its leading slash ("Sales/West", or the unit's unique ID), unlike the org-unit tools where the leading slash is part of the path.

[Google Workspace] Retrieve one ChromeOS device by its deviceId. Use projection="FULL" for the diagnostic detail — recent users, active time ranges, CPU and disk telemetry, and the auto-update expiration date that tells you when the hardware stops receiving Chrome updates. The deviceId is not the serial number; find it with gws_list_chromeos_devices, which accepts a "serial:" query term.

[Google Workspace] Check the outcome of a remote command previously sent with gws_issue_chromeos_device_command. Commands are queued, not immediate: a device that is powered off or off the network stays PENDING until it next checks in, and the state moves to EXECUTED_BY_CLIENT only once the device confirms. This is the only way to find out whether a wipe or reboot actually happened.

[Google Workspace] Send a remote command to one ChromeOS device. Destructive because the command set includes WIPE_USERS (erases every local user profile and their offline data) and REMOTE_POWERWASH (factory-resets the device, destroying anything not synced). The safe members of the same set are REBOOT, TAKE_A_SCREENSHOT, SET_VOLUME, DEVICE_START_CRD_SESSION and FETCH_SUPPORT_PACKET. Commands are queued: an offline device runs it at next check-in, and gws_get_chromeos_device_command is how you learn whether it ran. Some commands require a payload — SET_VOLUME takes {"volume":50} as a JSON string.

[Google Workspace] List enrolled ChromeOS devices. Caps at 100 per page — pass the response's nextPageToken back as pageToken for the next one. Narrow with orgUnitPath (add includeChildOrgunits=true to sweep the subtree beneath it) or with query, which accepts terms like "user:jsmith@example.com", "serial:5CD123", "status:provisioned" and "asset_id:". Google documents orgUnitPath here WITHOUT its leading slash ("Sales/West", or the unit's unique ID), unlike the org-unit tools where the leading slash is part of the path. projection="FULL" adds the fields most fleet questions actually need — last known user, last sync time, boot mode and OS version — at the cost of a much larger response, so prefer the default BASIC when listing a whole fleet.

[Google Workspace] Move up to 50 ChromeOS devices into a different organizational unit in one call. Reversible — move them back the same way — but not inconsequential: a device takes on the policy of its new org unit, so this can change sign-in restrictions, allowed apps and update settings for every device moved. Body: {"deviceIds":["id1","id2"]}. Pass the destination as orgUnitPath, e.g. "/Sales/Loaners".

[Google Workspace] Update named annotation fields on a ChromeOS device, merging rather than replacing. The right tool for recording an asset tag ({"annotatedAssetId":"IT-0417"}), the assigned user ({"annotatedUser":"jsmith@example.com"}), a location, or free-text notes. Note that annotatedUser is a label for your own records — it does not restrict who can sign in to the device.

[Google Workspace] REPLACE a ChromeOS device's editable record wholesale. Google's PUT: fields omitted from the body are cleared, so an asset tag, assigned user or location note not included in the body is erased. Prefer gws_patch_chromeos_device for ordinary edits. Only the administrative annotation fields are writable — hardware and telemetry are read-only.

[Google Workspace] Remove a mobile device from management. This deletes the enrollment record, so the device disappears from the admin console and from every device report — but it does NOT erase anything on the device, and a device whose account is still signed in will simply re-enroll at the next sync. To remove company data from the handset, use gws_issue_mobile_device_action with an account wipe instead; to stop it coming back, remove the account from the device or suspend the user first.

[Google Workspace] Retrieve one enrolled mobile device by its resourceId. projection="FULL" adds the security detail — encryption state, whether the device reports as compromised, screen-lock status, the accounts synced to it and the last sync time. Take the resourceId from gws_list_mobile_devices; the deviceId field in the response is the vendor's identifier and will not work here.

[Google Workspace] Send a management action to an enrolled mobile device. Destructive, and the two wipe actions differ in a way that matters to the device's owner: "admin_account_wipe" removes only the Workspace account and its data, leaving personal photos and apps intact, while "admin_remote_wipe" FACTORY RESETS THE ENTIRE DEVICE, erasing everything on it including personal data. On a personal phone under a BYOD arrangement, the account wipe is almost always the intended one. The other actions are "approve", "block" (blocks sync but leaves data in place), "cancel_remote_wipe_then_activate" and "cancel_remote_wipe_then_block", the last two of which cancel a pending wipe that has not yet reached the device.

[Google Workspace] List enrolled mobile devices. Caps at 100 per page — pass nextPageToken back as pageToken. query accepts terms such as "email:jsmith@example.com", "model:", "os:" and "id:". Use projection="FULL" to see the security posture fields an audit usually wants: encryption status, whether the device is compromised or rooted, password status and last sync time. A device that has not synced in months is usually retired hardware still holding an active account.

[Google Workspace] Add a secondary domain to the Workspace account. Additive, and it does NOT start routing mail: the domain arrives unverified, and someone must publish the verification record Google asks for in DNS before accounts on it work. Add a domain when its users need their OWN accounts; if the intent is simply a second address for existing people, gws_create_domain_alias is the right tool and needs no new licences. Body: {"domainName":"example.net"}.

[Google Workspace] Add a domain alias, giving every existing mailbox in the parent domain a second address at the alias domain. Additive and licence-free, but it still requires DNS verification before mail flows, and it applies to EVERY user in the parent domain at once — there is no way to alias only some of them. Body: {"domainAliasName":"example.net","parentDomainName":"example.com"}.

[Google Workspace] Remove a secondary domain from the Workspace account. Destructive and wide-reaching: mail to every address on that domain stops being delivered. Google refuses while any user or group still has an address there, so the failure mode is usually a clear error rather than silent data loss — but the accounts you delete to clear the way are the real loss. The primary domain cannot be removed at all. Run gws_list_users with a domain filter first to see who is affected.

[Google Workspace] Remove a domain alias. Destructive: mail sent to any address at the alias domain immediately starts bouncing, for every user in the parent domain at once, and senders with the old address in their address books will keep using it. Nothing in the mailboxes is deleted — the addresses simply stop existing.

[Google Workspace] Retrieve one domain by name, e.g. "example.com". The response includes its verification state, whether it is the primary domain, and the list of domain aliases attached to it.

[Google Workspace] Retrieve one domain alias by name, e.g. "example.net". The response names the parent domain it delivers into and whether Google has verified ownership of the alias.

[Google Workspace] List domain aliases. UNPAGINATED. Pass parentDomainName to see only the aliases attached to one domain. A domain alias delivers mail for a second domain name into the existing mailboxes of its parent domain, without any additional accounts or licences — which is why a customer with several trading names usually has aliases rather than domains.

[Google Workspace] List every domain the Workspace account owns. UNPAGINATED — the full set comes back in one response. Each entry carries whether it is the primary domain, whether Google has verified ownership, and its creation time. An unverified domain is the usual explanation for mail to it failing while the account otherwise looks correctly configured.

[Google Workspace] Remove policy values from one or more groups. Destructive: the values are discarded with no record of what they were, and every member of the group falls back to whatever their organizational unit says — which may be less restrictive than the group policy was. Capture the current values with gws_resolve_chrome_policies first.

[Google Workspace] Reset policies on organizational units so they inherit from their parent again. Destructive: the local settings are DISCARDED, not disabled, and there is no record of what they were — the only way back is to know the old values and set them again. The effective behaviour then jumps to whatever the parent says, which may be more permissive than what the unit was enforcing. Capture the current values with gws_resolve_chrome_policies before running this.

[Google Workspace] Set Chrome policy values on one or more groups. Destructive by blast radius, as the org-unit version is, with one extra subtlety: group policy is resolved by PRIORITY, so a change here may be silently overridden by a higher-priority group and appear to have done nothing. Check the ordering with gws_list_chrome_group_policy_priority when a change does not take effect.

[Google Workspace] Set Chrome policy values on one or more organizational units. Destructive by blast radius: the change applies immediately to EVERY user or device in the target unit and, through inheritance, to everything beneath it — a single call can, for example, strip the Wi-Fi configuration from every managed Chromebook in a site. Each request carries an updateMask naming the fields to write, so fields left out of the mask keep their current values. Read the effective policy first with gws_resolve_chrome_policies and confirm the target org unit is the one you mean.

[Google Workspace] Add a certificate for managed Chrome devices to trust. Additive. Typically a private certificate authority so devices trust an internal service, or a client certificate for network authentication. Body carries the target org unit, a settings block and the PEM certificate.

[Google Workspace] Define a network (Wi-Fi, Ethernet or VPN) that managed Chrome devices can be given. Additive — it creates the definition; devices receive it when a policy applies it to their organizational unit. Body carries the target org unit and an ONC network configuration.

[Google Workspace] Retrieve one Chrome policy schema by name, e.g. "chrome.users.AllowDinosaurEasterEgg", with its field definitions, legal values, and any notices about settings Google has deprecated. The definitive answer to "what exactly can I set here, and to what?".

[Google Workspace] Read the priority order of groups for one policy schema — which group's setting wins when a user belongs to several groups that all set it. A read despite being a POST. Worth checking before changing any group policy: the change may be overridden by a higher-priority group and appear to do nothing. Body: {"policyNamespace":"chrome.users","policySchema":"chrome.users.ChromeAdvancedProtection"}.

[Google Workspace] List the Chrome policy schemas available to the customer — the vocabulary of every setting that can be managed, with its fields and legal values. filter narrows by name, e.g. "name:chrome.users." for user policies or "name:chrome.devices." for device ones. Start here before any policy write: the schema name and field names have to be exact.

[Google Workspace] Remove a certificate from managed Chrome devices. Destructive: devices stop trusting it, so internal sites served under that authority start showing certificate warnings, and any network authentication depending on the certificate fails. Both failures look like a website or Wi-Fi problem rather than a policy change, which makes them slow to diagnose.

[Google Workspace] Remove a network definition. Destructive and immediately visible to users: managed Chrome devices relying on this network to reach the internet LOSE THEIR CONNECTION, and a device that can no longer connect cannot be managed remotely to fix it. On a site whose Chromebooks have no other configured network, this is how a fleet is stranded. Confirm an alternative network is in place first.

[Google Workspace] Change which group's policy wins for a schema when a user belongs to several. Not destructive — no values are lost and the ordering can be set back — but it CHANGES THE EFFECTIVE POLICY for everyone in those groups, so the visible result can be as large as editing the policies themselves. Body: {"policyNamespace":"chrome.users","policySchema":"...","groupIds":["id1","id2"]}, ordered highest priority first. Read the current order first.

[Google Workspace] Read the policies currently in EFFECT for an organizational unit or group, including values inherited from a parent rather than set locally. A read despite being a POST — Google uses POST here because the request body is too large for a query string. This is the tool that answers "why is this Chromebook behaving like that?", since the effective value is often inherited from somewhere nobody thought to look. Body: {"policySchemaFilter":"chrome.users.*","policyTargetKey":{"targetResource":"orgunits/03ph8a2z1"}}.

[Google Workspace] Add accounts to an existing hold, extending preservation to them. Additive and the safe direction. Body: {"accountIds":["123...","456..."]} — NUMERIC user ids, or emails via the emails field. The response returns a status per account in request order, so check it: an account that failed to be added is an account that is not being preserved, and the overall call still succeeds.

[Google Workspace] Add an account as a collaborator on a matter. Additive, but understand what it grants: a collaborator can search and export the data the matter covers, which on a litigation matter is privileged material. Body: {"matterPermission":{"role":"COLLABORATOR","accountId":"123..."},"sendEmails":false,"ccMe":false}. accountId is the NUMERIC user id from gws_get_user, and sendEmails=true emails the person.

[Google Workspace] Close a Vault matter, marking the investigation finished. Reversible with gws_reopen_vault_matter, which is why it is not marked destructive. Be deliberate about it on a matter that still carries legal holds: Google's API reference does not state what closing does to them, so if the intent is to STOP preserving data, release the holds explicitly with gws_delete_vault_hold rather than assuming closing did it — and if the intent is to keep preserving, verify the holds are still listed afterwards with gws_list_vault_holds.

[Google Workspace] Count the accounts a Vault query would process, without exporting anything. Reads no message content and changes nothing, but it starts a long-running operation server-side, which is why it is not classified as a plain read. The sensible step before gws_create_vault_export: it tells you how large the export would be. Body carries the same query object an export takes.

[Google Workspace] Start an export of search results. Additive — it copies rather than removes — but it is not free of consequence: an export COPIES potentially privileged material out of Vault into Cloud Storage where a different set of people can reach it, and a broad query can produce an enormous amount of it. Run gws_count_vault_matter_accounts on the same query first to see the scale. Body: {"name":"...","query":{"corpus":"MAIL","dataScope":"ALL_DATA","searchMethod":"ACCOUNT","accountInfo":{"emails":["jsmith@example.com"]}},"exportOptions":}. Exports run asynchronously; poll gws_get_vault_export.

[Google Workspace] Add one account to a hold. Additive; the single-account counterpart to gws_add_vault_held_accounts. Body: {"accountId":"123..."} or {"email":"jsmith@example.com"}.

[Google Workspace] Create a legal hold, which starts preserving the covered data and overrides the customer's ordinary retention rules. Additive and the safe direction of travel — it preserves rather than removes. Body: {"name":"Smith mail hold","corpus":"MAIL","accounts":[{"accountId":"123..."}]}, or use orgUnit instead of accounts to cover a whole organizational unit including people added to it later. Put the hold in place BEFORE anyone starts deleting accounts.

[Google Workspace] Create a Vault matter. Additive — an empty container that preserves nothing until a hold is created inside it. Body: {"name":"Smith v. Acme","description":"Litigation hold, opened 2026-08-13"}. Name it so a colleague can tell later what it is for; matters outlive the people who create them.

[Google Workspace] Save a search definition in a matter for reuse. Additive; it stores terms and searches nothing by itself. Body: {"displayName":"Smith mail, Q1","query":{"corpus":"MAIL","dataScope":"ALL_DATA","searchMethod":"ACCOUNT",...}}. Worth doing before a series of exports, so every one of them provably ran the same search.

[Google Workspace] Delete an export and the exported files it produced. Destructive and not recoverable: an export that took hours to produce has to be re-run from scratch, and if the underlying data has since been released from hold or purged, re-running it will not produce the same result. Deleting exports IS good hygiene once they have been collected — privileged material should not sit in Cloud Storage indefinitely — but confirm the files were downloaded first.

[Google Workspace] Remove one account from a legal hold. Destructive: that person's data stops being preserved and can be purged if nothing else holds it. The single-account counterpart to gws_remove_vault_held_accounts, and the same caution applies — this is a legal-obligation decision, not an IT tidy-up.

[Google Workspace] Release a legal hold. THE MOST CONSEQUENTIAL OPERATION IN THIS CONNECTOR. Google's own reference: this "releases the accounts or organizational unit covered by the hold. If the data is not preserved by another hold or retention rule, IT MIGHT BE PURGED." Evidence under a litigation hold can therefore start being deleted as a result of this call, which is a legal exposure and not merely a data one. Do not release a hold to tidy up, to reduce a list, or because a matter looks finished — releasing is a decision for whoever owns the legal obligation, not for whoever is doing the IT work.

[Google Workspace] Delete a Vault matter. Destructive and wide: the matter and everything in it — its holds, exports and saved queries — stop being active, and any data that was preserved ONLY by this matter's holds is no longer preserved. Google keeps the matter in a DELETED state so gws_undelete_vault_matter can bring it back, but the preservation gap in between is real. A matter must be CLOSED before it can be deleted.

[Google Workspace] Delete a saved query. Destructive but limited in blast radius: no message data is touched and no hold is affected — what is lost is the definition itself, which on a matter that has run several exports is the record of exactly what was searched for. Exports already produced are unaffected.

[Google Workspace] Retrieve one export by its exportId — its status, the query it ran, and once complete the Cloud Storage objects holding the results plus their MD5 hashes. The files themselves are not returned here; they are downloaded from Cloud Storage by whoever is authorized to, and the hashes are what proves the download is intact for an evidential chain.

[Google Workspace] Retrieve one legal hold by its holdId — the service it covers (MAIL, DRIVE, GROUPS, HANGOUTS_CHAT, VOICE), any query restricting it, and whether it applies to named accounts or a whole organizational unit. An org-unit hold covers everyone in that unit including people added later, which is a materially different scope from a list of accounts.

[Google Workspace] Retrieve one Vault matter by its matterId — its name, description, state and, with view="FULL", the accounts that can collaborate on it. Read this before any hold operation: whether a matter is OPEN or CLOSED determines what can be done inside it.

[Google Workspace] Retrieve one saved query by its savedQueryId, with the full query definition — corpus, date range, accounts or org unit, and search terms. Copy this into gws_create_vault_export to run exactly the search the team agreed on rather than an approximation of it.

[Google Workspace] List the exports in a matter, with each one's status and, once complete, the Cloud Storage location of the files it produced. Exports run asynchronously and can take hours for a large date range, so this is how to find out whether one has finished.

[Google Workspace] List the accounts covered by one hold. UNPAGINATED. Note this returns only accounts named INDIVIDUALLY: a hold scoped to an organizational unit covers everyone in that unit without listing them here, so an empty response does not mean nobody is being preserved. Check the hold itself with gws_get_vault_hold to see which kind it is.

[Google Workspace] List the legal holds in a matter — what each one covers (which service, which accounts or organizational unit) and when it was last updated. view="FULL_HOLD" includes the held accounts inline. This is the answer to "is this person's data being preserved?", and it is worth checking before any account deletion or retention change.

[Google Workspace] List Vault matters. state filters to "OPEN", "CLOSED" or "DELETED"; view takes "BASIC" or "FULL", where FULL adds the collaborator list. Note the default excludes deleted matters, so a missing matter may have been deleted rather than never created.

[Google Workspace] List the saved queries in a matter — the stored search definitions a team reuses so that repeated searches stay identical. Reading these is also the quickest way to understand what a matter is actually looking for.

[Google Workspace] Remove accounts from a legal hold. Destructive for the same reason as releasing the hold, narrowed to the named people: their data stops being preserved and, if nothing else preserves it, it can be purged. The response carries a status per account. Removing someone from a hold because they have left the company is exactly backwards — a departed employee's data is usually the reason the hold exists.

[Google Workspace] Remove an account's collaborator access to a matter. Destructive as an access revocation: that person immediately loses the ability to search or export the matter, and if they are the one running the investigation the work stops. Body: {"accountId":"123..."} — the NUMERIC user id.

[Google Workspace] Reopen a closed Vault matter so work can continue in it. Not destructive — it restores the matter to OPEN.

[Google Workspace] Restore a deleted Vault matter, returning it to the CLOSED state. Not destructive — it recovers. Reopen it afterwards with gws_reopen_vault_matter if holds need to be active again.

[Google Workspace] REPLACE a legal hold wholesale. Google's PUT, and on a hold the omission rule has legal weight: accounts left out of the body are no longer covered, and Google's reference is explicit that data released from a hold "might be purged" if nothing else preserves it. A partial body here is not a formatting mistake, it is a preservation failure. Read the hold with gws_get_vault_hold using view="FULL_HOLD" and send it back complete, or use the account-level tools instead.

[Google Workspace] REPLACE a matter's name and description wholesale. Google's PUT, so an omitted field is cleared — and on a legal matter the description is often the only record of why it exists and what it covers. Read the current record with gws_get_vault_matter and send it back complete.

[Google Workspace] Assign a licence to a user. MARKED AS CHANGING THINGS BECAUSE IT SPENDS THE CUSTOMER'S MONEY: taking up a seat the customer has not already paid for adds a charge to their next Google bill, and on an annual commitment it can extend the commitment rather than simply adding a month. Nothing is deleted and it is reversible with gws_delete_license_assignment, but the billing consequence is real and immediate. Confirm the customer has spare seats before assigning — the count of ASSIGNED seats is gws_list_license_assignments_for_sku; the count of PURCHASED seats lives in their Google billing account and is not in this API.

[Google Workspace] Revoke a user's licence. Destructive: THE USER LOSES THE PAID SERVICE, which for the main Workspace SKU means losing access to their mail and Drive while the account still exists — an outage that looks nothing like a licensing change from their side. Revoking also frees the seat, which is the point when offboarding, but do the data transfer first (gws_create_data_transfer) because a user without a licence is not a user you can still move data from.

[Google Workspace] Check whether one specific user holds one specific SKU. Returns the assignment or a 404 if they do not have it, so a 404 here is an answer rather than a fault. userId is the user's CURRENT primary email address.

[Google Workspace] List everyone holding a licence for one product, across all of its SKUs. productId is Google's product code — "Google-Apps" for Workspace itself, "101031" for Workspace Enterprise, "Google-Vault" for Vault. IMPORTANT: this API requires the NUMERIC customer id in the C00000000 form and does not accept the "my_customer" shorthand the other Google Workspace tools take; read the real id from gws_get_customer and pass it if the call is rejected. Caps at 1000 per page.

[Google Workspace] List everyone holding one specific SKU. This is the count that matters for a licence audit — how many seats of THIS edition are actually assigned, as opposed to how many the customer is paying for, which lives in their Google billing account and not in this API. Requires the numeric customer id in the C00000000 form, as above. Caps at 1000 per page.

[Google Workspace] Move a user to a different SKU, merging rather than replacing. The right tool for an upgrade or downgrade between editions. Not marked destructive because nothing is removed and the user keeps a licence throughout — but it still changes what the customer is billed for, so confirm the target SKU is one they have seats for. Body: {"productId":"Google-Apps","skuId":"1010020027","userId":"jsmith@example.com"}.

[Google Workspace] REPLACE a licence assignment wholesale — the route Google provides for moving a user from one SKU to another. Destructive on both counts that matter: it is a PUT, so omitted fields are cleared, and it changes what the customer is billed for, potentially in both directions at once. Body: {"productId":"Google-Apps","skuId":"1010020027","userId":"jsmith@example.com"}, where the path names the CURRENT assignment and the body names the new SKU. Prefer gws_patch_license_assignment.

[Google Workspace] Soft-delete many alerts at once. Body: {"alertId":["id1","id2"]}. Recoverable with gws_batch_undelete_alerts, but the scale is the risk: a filter that matched more alerts than expected clears a security queue in one call, and the response's failedAlertStatus map is the only record of which ones did not go. Read the list you intend to delete before sending it.

[Google Workspace] Restore many soft-deleted alerts at once. Body: {"alertId":["id1","id2"]}. Not destructive — it recovers. The counterpart to gws_batch_delete_alerts, and the way back from a bulk delete that matched too much.

[Google Workspace] Record feedback on an alert. Additive — feedback accumulates and nothing is overwritten. feedbackType is one of "VERY_USEFUL", "SOMEWHAT_USEFUL", "NOT_USEFUL". This is how a team marks an alert as triaged, and Google also uses it to tune future detections for the domain.

[Google Workspace] Delete one alert. RECOVERABLE — this is a soft delete, and gws_undelete_alert restores it within Google's retention window — but it removes the alert from the default list, so it becomes an alert nobody reviews. Marked as changing things for that reason rather than because anything is permanently lost. Prefer recording feedback with gws_create_alert_feedback over deleting: the alert stays auditable and still counts as triaged.

[Google Workspace] Retrieve one alert by its alertId, with its full payload — the affected users, the detection detail, and the timestamps. The payload shape differs per alert type, which is why it passes through exactly as Google sends it rather than being reshaped into a common form that would lose the type-specific fields.

[Google Workspace] Read one alert's workflow metadata — its assignee, severity and current status — as distinct from the alert's own detection payload. This is the triage state a team maintains around an alert, not what Google detected.

[Google Workspace] Read the domain's Alert Center notification settings — which alert types raise an email notification and to which addresses. Worth checking when a customer says they were never told about an incident: the alert may have been raised correctly and simply notified nobody.

[Google Workspace] List the feedback recorded against one alert — whether an administrator marked it a real threat, not useful, or a false positive, and when. Useful for seeing whether an alert has already been triaged by someone before acting on it again.

[Google Workspace] List security and compliance alerts for the domain. filter accepts terms such as "type='Suspicious login'", "source='Google Identity'", "createTime >= "2026-08-01T00:00:00Z"" and "isState=false"; orderBy takes "create_time desc" for newest first. Alert types worth knowing by name: "Suspicious login", "Government backed attack", "Leaked password", "Malware reclassification", "Suspicious message reported" and "Device compromised". Note that deleted alerts are excluded by default, so a missing alert may have been deleted rather than never raised.

[Google Workspace] Update the domain's Alert Center notification settings — which alert types email a human, and which addresses. A merging PATCH, so named settings change and the rest are left alone. Body: {"notifications":[{"cloudPubsubTopic":}]}. Take care that removing an address here silently stops someone being told about incidents.

[Google Workspace] Restore a soft-deleted alert, putting it back in the default list. Not destructive — it recovers something. Only works within Google's retention window; an alert deleted long enough ago cannot be brought back.

[Google Workspace] Domain-wide usage figures for a single day — account counts, storage consumed, and per-service activity totals across Gmail, Drive, Calendar, Meet and Classroom. date is "yyyy-mm-dd" and must be a COMPLETED day; today's report does not exist, and the most recent complete day may still be a day or two from being available. Narrow the response with parameters, e.g. "accounts:num_users,drive:num_items_created", since the default report is very large.

[Google Workspace] Usage for non-user entities on a single day. entityType is the entity class — Google's supported value here is "gplus_communities" — and entityKey names one entity or is left empty for all of them. This is the narrowest of the three usage reports and the one most likely to return nothing for an ordinary business domain; gws_get_customer_usage_report and gws_get_user_usage_report answer almost every real question. date is "yyyy-mm-dd" and must be a completed day.

[Google Workspace] Per-user usage for a single day — last sign-in, whether 2-step verification is enrolled, mailbox and Drive storage used, and per-service activity. Leave userKey empty for every user in the domain, which is how to answer questions like "who has not signed in for months?" or "who is not on 2SV?" in one call rather than per person. date is "yyyy-mm-dd" and must be a completed day. Narrow with parameters, e.g. "accounts:last_login_time,accounts:is_2sv_enrolled". Caps at 1000 per page.

[Google Workspace] Read the audit log for one application. applicationName selects which log: "login" (sign-ins, including failures and suspicious-login flags), "admin" (every administrative change and who made it), "drive", "token" (third-party app authorizations), "user_accounts", "groups", "mobile", "saml", "rules", "chrome", "calendar", "meet" and more. Leave userKey empty for the whole domain or pass an address to follow one person. Narrow with startTime and endTime (RFC 3339, e.g. "2026-08-01T00:00:00Z"), eventName, or actorIpAddress. IMPORTANT: this data lags — usually hours, occasionally up to three days — so an empty result may mean "not indexed yet" rather than "did not happen". Caps at 1000 per page.

[Google Workspace] Read a group's policy — who can post, who can join, who can view the member list and the archive, whether messages are moderated, and whether people outside the organization can email it. Keyed by the group's EMAIL ADDRESS, e.g. "support@example.com", not by the id the Directory tools return. This is where to look when mail from outside is bouncing off a group: whoCanPostMessage is usually the answer, and it is invisible in gws_get_group.

[Google Workspace] Change named group settings, leaving the rest alone. The right tool for the common jobs: letting outsiders email a support alias ({"whoCanPostMessage":"ANYONE_CAN_POST"}), turning off moderation ({"messageModerationLevel":"MODERATE_NONE"}), or restricting who can see the member list ({"whoCanViewMembership":"ALL_MANAGERS_CAN_VIEW"}). Values are Google's enum strings and are case-sensitive. Read the current settings first if you are unsure which of the several similarly-named whoCan* settings governs the behaviour you mean.

[Google Workspace] REPLACE a group's policy wholesale. Google's PUT: every setting omitted from the body reverts to its default, which on this API means a partial body can quietly OPEN A GROUP UP — posting rights, membership approval and archive visibility all fall back to defaults that may be more permissive than what the customer configured. Prefer gws_patch_group_settings for every ordinary change; if this really is the right tool, read the current settings with gws_get_group_settings and send them back complete.

[Google Workspace] Start transferring a departing user's application data to another user. Additive — the receiving user GAINS copies and the original owner keeps theirs, so nothing is destroyed — but it is not instant, and it must complete BEFORE the source account is deleted or the data goes with the account. Body: {"oldOwnerUserId":"123...","newOwnerUserId":"456...","applicationDataTransfers":[{"applicationId":"55656082996","applicationTransferParams":[{"key":"PRIVACY_LEVEL","value":["PRIVATE","SHARED"]}]}]}. Both user ids are NUMERIC, from gws_get_user; applicationId and the parameter names come from gws_list_transfer_applications. Poll gws_get_data_transfer until it completes.

[Google Workspace] Retrieve one data transfer by its id, with the per-application status of each part of it. A transfer can be partly done — Drive completed while Calendar failed — so the overall status is not the whole story, and this is the tool that shows the breakdown.

[Google Workspace] Retrieve one transferable application by its numeric applicationId, with the exact transferParams it accepts and the legal values for each — for Drive, for example, the privacy level controlling whether private files move along with shared ones.

[Google Workspace] List data transfers, most recent first. Filter by oldOwnerUserId or newOwnerUserId (both are NUMERIC user ids, not email addresses — take them from gws_get_user) or by status: "inProgress", "completed" or "failed". The way to confirm that an offboarding actually finished before the departing account is deleted.

[Google Workspace] List the applications whose data can be transferred between users — typically Drive and Docs, Calendar, and Google+ where still present. Each entry carries its numeric applicationId and the transferParams it accepts, both of which gws_create_data_transfer needs. Start here: the parameter names and values are per-application and cannot be guessed.

[Google Workspace] Create a building. Additive; it holds no rooms until rooms name it. Body: {"buildingId":"NYC-01","buildingName":"New York HQ","floorNames":["G","1","2"],"address":{"addressLines":["..."],"regionCode":"US"}}. buildingId is chosen by you and immutable afterwards, so pick something the customer will still recognize in two years. Set coordinatesSource to RESOLVED_FROM_ADDRESS to let Google geocode the address rather than supplying coordinates yourself.

[Google Workspace] Create a resource feature. Additive; it tags nothing until a room names it. Body: {"name":"Whiteboard"}. The name is what users see in the room picker's filters, so write it the way they would look for it.

[Google Workspace] Create a bookable resource. Additive; Google generates its resourceEmail and it becomes bookable straight away. Body: {"resourceId":"nyc-1-conf-a","resourceName":"Conference A","resourceCategory":"CONFERENCE_ROOM","capacity":10,"buildingId":"NYC-01","floorName":"1"}. resourceId is chosen by you and immutable. floorName must exactly match one of the building's floorNames or the room will not group correctly, and buildingId must name a building that already exists.

[Google Workspace] Delete a building. Destructive: Google refuses while rooms still reference it, so clear or move those first — and be aware that reassigning rooms to a different building changes where they appear in everyone's room picker. Existing bookings are unaffected either way; this is directory data, not calendar data.

[Google Workspace] Delete a resource feature. Destructive: every room tagged with it loses the tag, so rooms that were findable by filtering on this feature stop appearing in those searches — an accessibility or video-conferencing tag is exactly the kind whose loss strands the people who depend on it. To change a label, use gws_rename_calendar_feature rather than deleting and recreating.

[Google Workspace] Delete a bookable resource. Destructive, and the failure mode is quiet rather than loud: the room's calendar and its resourceEmail go, so EXISTING MEETINGS BOOKED INTO IT KEEP THEIR ROOM LINE BUT THE ROOM NO LONGER EXISTS — organizers are not notified and nobody finds out until they turn up. Check for future bookings before deleting a room that is in use, and prefer renaming or re-tagging when the room is merely being repurposed.

[Google Workspace] Retrieve one building by its buildingId, including its floor list and postal address. The floor names matter beyond labelling: a room's floorName has to match one of the strings here for the room to appear in the right place when people book.

[Google Workspace] Retrieve one resource feature by name. Features are identified BY THEIR NAME rather than by a generated id, which is why renaming one has its own tool — see gws_rename_calendar_feature.

[Google Workspace] Retrieve one bookable resource by its resourceId — its name, category, capacity, building and floor, the features it is tagged with, and its resourceEmail. Note the two names: resourceName is what you set, while generatedResourceName is the composed display name Google shows in the room picker, and only the second is what users will recognize.

[Google Workspace] List the buildings defined for the domain, with their floor names, addresses and map coordinates. Buildings are the geography that rooms are organized under — Google groups room suggestions by building and floor when someone books a meeting, so a domain with rooms but no buildings gives people a flat list to hunt through.

[Google Workspace] List the resource features defined for the domain — the tags such as "Whiteboard", "Video conferencing" or "Step-free access" that rooms are marked with and that people filter on when booking. A feature must exist here before any room can be tagged with it.

[Google Workspace] List bookable calendar resources — meeting rooms, equipment, and anything else people can book. query filters on resource fields, e.g. "resourceCategory=CONFERENCE_ROOM", "buildingId=NYC-01" or "capacity>=10"; orderBy sorts on fields such as "buildingId,capacity". Each entry carries the generated resourceEmail, which is the address a meeting invitation has to be sent to for the room to be booked.

[Google Workspace] Update named fields on a building, merging rather than replacing. The right tool for renaming it, correcting its address, or adding a floor — though note that supplying floorNames replaces the whole array, so build the complete floor list from gws_get_building first.

[Google Workspace] Update named fields on a resource feature, merging rather than replacing. There is little to change on a feature beyond its name, and gws_rename_calendar_feature is the right tool for that — this exists for completeness and for any field Google adds later.

[Google Workspace] Update named fields on a bookable resource, merging rather than replacing. The right tool for correcting a capacity, moving a room to another floor, or re-tagging its features ({"featureInstances":[{"feature":{"name":"Whiteboard"}}]}) — bearing in mind that featureInstances, being a list, is replaced as a whole rather than merged.

[Google Workspace] Rename a resource feature, keeping every room tagged with it attached. This exists as its own operation because features are keyed by name: deleting and recreating one to change its label would untag every room in the domain, whereas this changes the label in place.

[Google Workspace] REPLACE a building wholesale. Google's PUT: omitted fields are cleared, and an omitted floorNames array empties the floor list — which detaches every room whose floorName referred to one of them. Prefer gws_patch_building, and read the current record with gws_get_building before sending a complete one.

[Google Workspace] REPLACE a resource feature wholesale. Google's PUT, so it carries the usual clear-what-is-omitted semantics. For the one thing anyone actually wants to do here — changing a feature's name — use gws_rename_calendar_feature instead: it is the operation Google provides for it, and it keeps the rooms tagged with the feature attached to it.

[Google Workspace] REPLACE a bookable resource wholesale. Google's PUT: omitted fields are cleared, so a body that names only the capacity strips the building, floor and feature tags — leaving a room that still exists and still takes bookings but has fallen out of every filtered room picker. Prefer gws_patch_calendar_resource; read the current record first if this is genuinely the right tool.

[Google Workspace] Create a custom user schema. Additive — it defines fields, sets no values, and changes nothing about existing users. Body: {"schemaName":"EmployeeInfo","displayName":"Employee Info","fields":[{"fieldName":"employeeNumber","fieldType":"STRING","multiValued":false,"readAccessType":"ADMINS_AND_SELF"}]}. Field types are STRING, INT64, BOOL, DATE, DOUBLE, EMAIL and PHONE. Choose fieldType carefully: it cannot be changed later, so a field created as STRING stays STRING even if it only ever holds numbers.

[Google Workspace] Delete a custom user schema. Destructive well beyond the definition itself: EVERY user's stored values for every field in this schema are deleted with it, across the entire directory, and there is no undo and no export on the way out. If those values are the customer's only record of employee numbers or start dates, they are gone. Export them first by reading users with projection="FULL".

[Google Workspace] Retrieve one custom schema by name or id, with its full field list — each field's type, whether it accepts multiple values, and its read-access setting (ADMINS_AND_SELF keeps a field private to administrators and the user themselves, rather than visible across the directory).

[Google Workspace] List the custom schemas defined for the domain — the extra user fields a customer has added, such as employee number, start date or cost centre. UNPAGINATED. Read this before querying users by a custom field: gws_list_users accepts a query like "EmployeeInfo.employeeNumber=12345", and both halves of that name have to match a real schema and field exactly.

[Google Workspace] Update named properties of a custom schema, merging rather than replacing. The right tool for changing a display name. Be aware that the fields array is still replaced as a whole when supplied — merging applies to top-level properties, not to list contents — so to add a field, read the existing definition with gws_get_schema, append to its fields array, and send the complete array back.

[Google Workspace] REPLACE a custom schema wholesale. Google's PUT: any field omitted from the body is removed from the schema, and removing a field DELETES the value every user had stored in it. That makes an incomplete body a silent data loss across the whole directory rather than a rejected request. Read the current definition with gws_get_schema and send it back complete, or use gws_patch_schema instead.

[Google Workspace] Revoke one of a user's application-specific passwords. Destructive: whatever was using it stops authenticating immediately, and because these are typically old mail clients, scanners and copiers, the breakage often shows up somewhere nobody connected to this change. It cannot be restored — the user has to create a new one and reconfigure the device. Check the last-used time with gws_get_user_app_password first; a password unused for months is a safe revocation, one used this morning is not.

[Google Workspace] Revoke a third-party application's access to a user's Google account. Destructive and it can reach further than intended: the same mechanism that removes an attacker's app also removes the customer's own integrations, so revoking a token can silently break a backup tool, a CRM sync or a signature manager that nobody associates with this action. Read the grant with gws_get_user_token first and confirm what the application is. To cut off everything at once during an incident, gws_sign_out_user plus a password reset is the broader hammer.

[Google Workspace] Generate a fresh set of 2-step verification backup codes for a user. Not destructive — the user ends up with working codes — but note the side effect: this REPLACES the existing set, so any codes the user has printed or saved stop working the moment it runs. Read the new set with gws_list_user_verification_codes afterwards. The user must already be enrolled in 2-step verification for this to succeed.

[Google Workspace] Retrieve one application-specific password record by its codeId — the name the user gave it, when it was created and when it was last used. The password value is never returned by the API and cannot be recovered; a lost app password has to be revoked and reissued by the user.

[Google Workspace] Retrieve one third-party application grant for a user, keyed by the application's OAuth client id, including the exact scopes it holds and whether it is a native application. Read the scopes before revoking: a grant with a mail scope is a very different thing from one with a calendar-read scope.

[Google Workspace] Invalidate every one of a user's 2-step verification backup codes without issuing new ones. Destructive: the codes are gone, and a user who then loses their phone has no backup route into the account and will need an administrator to help them recover it. The right response to backup codes having been exposed — in a shared document, a screenshot or a compromised mailbox. If the user still needs codes, gws_generate_user_verification_codes both invalidates the old set and issues a new one in a single step.

[Google Workspace] List a user's application-specific passwords — the single-purpose passwords issued for older clients that cannot complete 2-step verification. The response names each one and when it was last used, never the password itself. Worth auditing: an app password bypasses 2SV by design, so a forgotten one on a decommissioned device is a standing way into the account. UNPAGINATED.

[Google Workspace] List the third-party applications a user has granted access to their Google account, with the scopes each was given. The first place to look after a phishing report or a suspicious-login alert: an attacker who has authorized their own OAuth app keeps access even after a password reset, because the token is independent of the password. Also the honest inventory for an offboarding — every entry is something still able to read that person's data. UNPAGINATED.

[Google Workspace] List a user's current 2-step verification backup codes. HANDLE THE RESPONSE AS A CREDENTIAL: it contains the usable codes themselves, each of which completes 2SV for that account once. This exists so an administrator can read a code to a locked-out user over a verified phone call — do not paste the response anywhere it will persist, such as a ticket note or a chat channel. UNPAGINATED.

[Google Workspace] Turn off 2-step verification for a user, unenrolling them entirely. Destructive in the security sense rather than the data sense: it LOWERS THE CUSTOMER'S SECURITY POSTURE, leaving that account protected by its password alone, and it may breach a policy or an insurance requirement the customer has signed up to. The legitimate use is a user who has lost every second factor and has no backup codes; the safer alternatives are reading them a backup code with gws_list_user_verification_codes or issuing a new set. If it is used for a recovery, re-enrollment is the user's own action — nothing here turns it back on.