The short version
A normal OAuth app asks each user for permission. That works for consumer software and falls apart the moment you want a background job to process every mailbox in a company at three in the morning. Domain-wide delegation removes the user from the loop entirely.
You create a service account, take its numeric client ID, and a Workspace super administrator authorizes that client ID for a specific list of OAuth scopes. From then on, your code asks Google for a token as a named user — the subject — and Google issues it, provided every scope in the request appears in the authorized list.
When it is the right tool
- Server-side automation across many users — archiving mail, syncing calendars, provisioning Drive folders, running reports across a domain.
- Agents and internal tools that act on behalf of staff — drafting replies in a shared mailbox, filing documents, updating sheets, without asking each person to authorize an app.
- Work that must survive people leaving — a delegated service account keeps running when the employee who would have consented is gone.
When it is the wrong tool
- Anything user-facing where consent is meaningful. If the person should be able to say no, use standard OAuth.
- Consumer Gmail accounts. Delegation is a Workspace feature. There is no equivalent for @gmail.com.
- Access you want scoped to one mailbox forever. The grant is domain-wide. Discipline about scopes and subjects is the only real boundary.
The four things that go wrong
Scope mismatch
The code requests a scope the Admin console never authorized. Returns unauthorized_client, with no indication of which scope is at fault.
No storage quota
Creating Drive files as the bare service account instead of impersonating a user yields storageQuotaExceeded. Service accounts own no storage.
Wrong admin, wrong console
The grant lives in the Workspace Admin console, not Google Cloud, and needs a super administrator of the domain you are impersonating into.
Setup walkthrough →Propagation and silence
New scope grants are not always instant, and a stale cached token keeps failing after you fix the cause. Mint a fresh token before concluding anything.
Diagnosis order →Multiple domains
One service account can be delegated in several Workspace tenants at once. The same client ID is authorized separately in each Admin console, with its own scope list, and your code picks a tenant simply by choosing which user it impersonates. This is how a single automation estate spans several companies without a separate credential for each — and it is where most homegrown setups get tangled, because a scope authorized in one tenant is not authorized in another.
Common questions
What is domain-wide delegation?
Domain-wide delegation is a Google Workspace setting that authorizes a service account to impersonate users in your domain and call Google APIs as them, without each user granting consent individually. The service account requests a token with a subject — the user it is acting as — and Google issues it if a super administrator has authorized that client ID for the exact scopes being requested.
Is domain-wide delegation the same as a service account?
No. A service account is an identity. Domain-wide delegation is permission granted to that identity by a Workspace super administrator, allowing it to impersonate human users. A service account with no delegation can only access what it owns, which is why it has no Gmail mailbox and no Drive storage quota of its own.
Do users get a consent screen with domain-wide delegation?
No. That is the point, and also the risk. Once a client ID is authorized for a scope, the service account can act as any user in the domain for that scope, silently. There is no per-user prompt and no per-user opt-out.
Why does my delegation return unauthorized_client?
Almost always a scope mismatch: the scope string requested in code is not in the list authorized in the Admin console for that client ID. Scopes are matched exactly, one at a time. A single extra scope in the request that was never authorized fails the whole token exchange.
Can domain-wide delegation be limited to one user?
Not by the delegation grant itself, which is domain-wide by definition. You limit exposure by authorizing the narrowest scopes that do the job, and by controlling which subject your code impersonates. If you need true per-user restriction, use standard OAuth with user consent instead.
Want this working today rather than next week?
We set up domain-wide delegation for a living — single tenant or several, with the scope list, the impersonation code, and a verification pass that proves each API actually answers before we hand it over. $500 per hour, and most single-tenant setups are done inside one.
Talk to us about your setup