Google Workspace package v1.0.0

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.

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.

Approval classification: the three directory reads sit at the minimum R0 tier 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 minimum R3 tier because a sent message cannot be recalled after delivery, and send is one of the designated actions requiring human approval.

On supported execution paths mediated by AAES Govern, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths.

The send capability's credential contract needs an honest delegation distinction, like the Teams handling in the Microsoft 365 package: 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 package has completed the documentation review: the dated method, scope and delegation sources are listed in the review record on this page, 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.