googleworkspace v1.0.0

The pack names a reference, never a secret. Installing a pack registers capabilities and makes them governable; registration is not connectivity. The credential is created at the provider and held in the client's own secret manager under the reference the pack names, and deployment testing is still required to show the credential path works and cannot be bypassed.

Reference

secret-ref-google-workspace-access-token

Custody

customer_vault

Injection

header (Authorization)

The value stored under this reference is the complete Authorization header value (scheme included): the scheme 'Bearer', one separating space, then an OAuth 2.0 access token for Google APIs — 'Bearer <token>'. The token is minted and renewed by an external token process, never by the executor: either a user-consent (delegated) OAuth 2.0 flow acting as one signed-in user, or a service account using the JWT-bearer grant against https://oauth2.googleapis.com/token — with domain-wide delegation and a 'sub' claim naming the impersonated user when the token must act as a user, which the Gmail send capability always requires because a service account has no mailbox access of its own. Google access tokens are short-lived (the token response's expires_in, typically about one hour), so renewal ownership sits with the external process, which obtains a replacement access token before expiry and stores the new complete header value; the executor injects the stored value verbatim and performs no token lifecycle itself. The stored value is never the service-account private key, the OAuth client secret or a refresh token — the service-account JSON key stays with the external token process, and losing it is a revocation event, not a vault rotation. Revocation: distinguish grant revocation from token invalidation. A user-consent grant can be revoked by the user or restricted by the Workspace admin, and removing a domain-wide delegation grant in the Admin console's Domain-wide delegation page stops the service account from minting further impersonated tokens — both cut off future token acquisition. Disabling or deleting a service-account key likewise stops future JWT signing and future token minting, but it is not revocation of access tokens already minted with that key: Google access tokens remain valid until their own expiry (the token response's expires_in, typically about one hour), subject to Google's revocation-propagation limits. Plan any emergency revocation around that residual validity window. An expired value fails closed. Least privilege: consent only the scopes these capabilities need — admin.directory.user.readonly, admin.directory.group.readonly (which also covers members.list), and gmail.send — and weigh before granting that gmail.send under domain-wide delegation lets the service account send as any authorized user in the domain. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only. Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

• google-workspace-users (api, pii): https://admin.googleapis.com/admin/directory/v1/users
• google-workspace-groups (api, internal): https://admin.googleapis.com/admin/directory/v1/groups
• google-workspace-mailbox (mailbox, pii): https://gmail.googleapis.com/gmail/v1/users/USER_ID

GROUP_KEY and USER_ID in the endpoint paths are placeholders: the deployment must substitute the concrete group and user each capability is bound to before enabling the pack, and the pack must not be enabled with the literals in place — the review does not rely on Google rejecting literal placeholder identifiers as the control, and allowlisting admin.googleapis.com or gmail.googleapis.com does not make an unsubstituted pack safe. The egress allowlist hosts are real shared Google API hosts, not placeholders: admin.googleapis.com serves the Admin SDK Directory API and gmail.googleapis.com serves the Gmail API, so they stay real and the allowlist does not move with the tenant. This pack registers only endpoints the official Google Workspace documentation publishes: Admin SDK Directory users.list, groups.list and members.list, and Gmail users.messages.send (the metadata URI, not the media-upload URI). users.list requires either the customer or domain query parameter and can retrieve deleted users via showDeleted — review which scoping the deployment binds. Documented exclusions: this pack does not register user creation, update, patch, deletion, undelete or makeAdmin (users.insert, users.update, users.patch, users.delete, users.undelete, users.makeAdmin), user alias and photo operations, group creation, update or deletion (groups.insert, groups.update, groups.patch, groups.delete), group membership writes (members.insert, members.update, members.patch, members.delete), organizational-unit, role, role-assignment, schema, token and device operations, the Reports and Alert Center APIs, and every other Gmail operation including message delete, batchDelete, modify, batchModify, import, insert, trash and settings/delegate management — a documented exclusion, not an approximated capability. Tiering rationale: the three directory reads sit at the R0 floor of read, with users and memberships at the pii class because names, email addresses and member identities are personal data. gmail.messages.send carries the send action at the R3 floor because a sent message cannot be un-sent, and send is one of the IRREVERSIBLE ACTIONS (delete, send, pay, deploy, approve, share and transfer); an irreversible action cannot be taken without a person. The send capability's credential contract needs an honest delegation distinction, like the microsoft365 pack's Teams handling: with a user-consent (delegated) OAuth 2.0 flow, the token acts as the signed-in user and USER_ID must be that user (or the special value 'me'); with a service account, Gmail has no application-level access at all — a service account reaches a user's mailbox only through domain-wide delegation, which a Google Workspace super administrator grants in the Admin console by authorizing the service account's numeric client ID with explicit OAuth scopes, after which the token process impersonates a named user (the JWT 'sub' claim) and acts with that user's permissions, never with elevated domain-wide privileges. The pack-level reference is deliberately flow-neutral; the deployment chooses the flow, binds USER_ID to the impersonated or signed-in user accordingly, and consents the minimum scopes — admin.directory.user.readonly and admin.directory.group.readonly for the reads, gmail.send (the least-privileged send scope) for the send. Domain-wide delegation is tenant-grade power: a mis-scoped DWD grant lets the service account impersonate any user in the domain within those scopes, so the authorized scope list and the service account's key custody are part of this pack's review. This pack is draft pending the manual library review recorded in review.state: the dated method, scope and delegation sources are listed in review.sources, and promotion requires a reviewer to complete that named-source check — library readiness does not require demonstrating a particular deployment's connectivity or executor operation.

Draft review record dated 2026-09-21 · Reviewer: aaes-eng (an opaque id that resolves internally to the responsible reviewer)

• https://developers.google.com/workspace/admin/directory/reference/rest/v1/users/list (retrieved 2026-09-21)
• https://developers.google.com/workspace/admin/directory/reference/rest/v1/groups/list (retrieved 2026-09-21)
• https://developers.google.com/workspace/admin/directory/reference/rest/v1/members/list (retrieved 2026-09-21)
• https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send (retrieved 2026-09-21)
• https://developers.google.com/identity/protocols/oauth2/service-account (retrieved 2026-09-21)
• https://developers.google.com/identity/protocols/oauth2 (retrieved 2026-09-21)
• https://support.google.com/a/answer/162106 (retrieved 2026-09-21)

A pack review is not a vendor or examiner attestation. A retrieval date says when a source page was read; it does not by itself establish what the page said then. No pack is vendor-endorsed, and none has been connectivity-tested against a live vendor tenant.