Google Domain-Wide Delegation

Google domain-wide delegation (DWD) lets a workspace Admin or Owner bind a service-account credential to one mailbox subject and a fixed Gmail scope set. Mailer polling and replies can then use a short-lived delegated access token instead of an end-user OAuth refresh.

Feature flag

DWD HTTP APIs return 404 { "error": "Google DWD is disabled" } unless FLUXUS_GOOGLE_DWD=true. Any other value, including unset, keeps DWD off.

What you configure

POST /api/v1/google-dwd (workspace API key, Admin or Owner) requires:

Allowlisted scopes:

• https://www.googleapis.com/auth/gmail.readonly
• https://www.googleapis.com/auth/gmail.modify
• https://www.googleapis.com/auth/gmail.send

Subject and scopes are immutable for a (credentialId, subject) pair. Changing scopes requires a new administrative connection. A new config starts enabled: false and testStatus: "pending". List/get responses serialize metadata only — never the private key or access token.

Test, then enable

POST /api/v1/google-dwd/{id}/test exchanges a JWT bearer assertion (iss = service-account email, sub = subject, scope = configured scopes, 1-hour exp) at https://oauth2.googleapis.com/token, then GETs https://gmail.googleapis.com/gmail/v1/users/{subject}/profile.

Success sets testStatus: "succeeded" and writes audit google_dwd.test. Failure sets testStatus: "failed", stores lastError, and disables the config.

PATCH /api/v1/google-dwd/{id} with { "enabled": true } is rejected until a successful test. Disable anytime with { "enabled": false }.

Runtime resolve (resolveGoogleDwdAccess) requires enabled + testStatus === "succeeded", an exact subject match, and at least one of the caller’s required scopes. Mailer polling asks for gmail.readonly or gmail.modify. Replies ask for gmail.send.

Bind to Mailer

PATCH /api/v1/mailer/routes/{id}/google-dwd (Admin/Owner, flag on) attaches or clears googleDwdConfigId. Attach requires:

• route provider is gmail
• route credentialId equals the config credential
• route address equals the fixed subject
• config includes gmail.readonly or gmail.modify

Polling groups may set googleDwdConfigId on create (Gmail only, same Admin/Owner check). Every active DWD route in the group must use that same subject. DWD tokens are used in-memory and are not written back as refreshed OAuth secrets.

Next steps