Domain-Wide Delegation
Domain-Wide Delegation (DWD) is the Google Workspace mechanism that lets SignatureCat's dedicated service account read your directory and write Gmail signatures - without ever knowing anyone's password. You grant it once in the Google Admin console; this page explains exactly what is granted and how it behaves over time.
The step-by-step setup lives in Connect your Google Workspace. This is the reference.
What exactly do I authorize?
You add one API client on the Admin console's Domain-wide delegation page, identified by a numeric Client ID that is unique to your organization (every SignatureCat customer has their own isolated service account). The Client ID is shown in the DWD wizard and later in Settings, Service Account section.
The scopes and what each one is for:
| Scope | Required | Used for |
|---|---|---|
gmail.settings.basic | Yes | Writing the signature on each user's primary address, and reading the stored signature back - the check that compares what Gmail saved with what was sent, and the on-demand mailbox lookup in Logs. |
admin.directory.user.readonly | Yes | Reading user profiles - names, job titles, phones - for template variables. |
admin.directory.group.member.readonly | Yes | Expanding group assignments into members. |
admin.directory.customer.readonly | Yes | Reading the workspace seat count for billing. |
gmail.settings.sharing | Optional | Writing signatures on send-as aliases. Skip it and alias features stay off. |
SignatureCat never asks for mail content scopes - it cannot read or send anyone's email.
Is the Client ID stable?
Yes. SignatureCat rotates its service-account keys automatically for security, but rotation mints a new key on the same service account - the numeric Client ID never changes. You will never need to re-authorize DWD because of key rotation.
How quickly does a new grant work?
Google propagates DWD changes eventually - usually seconds, occasionally up to about 30 seconds. The wizard's Check button waits out this window before reporting failure, so a single click typically succeeds right after you authorize. A yellow "propagating" card means exactly that: wait a moment and check again.
What happens if DWD is removed or a scope revoked?
SignatureCat verifies DWD health before every sync. When it breaks:
- signature syncs pause immediately (nothing is half-applied),
- admins get the in-app notification "Domain-Wide Delegation access lost" and an "Action required" email,
- admins see a red banner across the app: "The last Google Workspace access check failed. Signature syncs are paused until the access is fixed.",
- the app routes admins back to the DWD wizard.
The banner carries an inline Check access now button that re-runs the access check on the spot, without opening the wizard: if it passes, the banner disappears; if it still fails, you land in the wizard. There is also an Open the DWD wizard link. Only admins see the banner, because only they can re-authorize, and it appears only after a check has actually failed - never merely because a check is old.
Re-granting the missing entry or scope and passing Check resumes everything - state self-heals, nothing needs to be rebuilt. To re-open the wizard at any time use Re-run DWD wizard in Settings, Service Account section.
Adding the optional alias scope later
Add https://www.googleapis.com/auth/gmail.settings.sharing to the existing Admin console entry (keep the other four scopes), then Re-run DWD wizard and click Check. Alias features unlock automatically - see alias modes.
Removing SignatureCat
When you delete your account, SignatureCat removes its own infrastructure, but it cannot edit your Admin console: delete the API client entry yourself on the Domain-wide delegation page after the account is gone.