Troubleshooting domain-wide delegation

Delegation fails in a small number of recognisable ways. The trick is knowing whether the failure happened at token time or call time — that single distinction cuts the search space in half.

Diagnose in this order. First: did you get a token at all? A token failure is a grant problem — client ID, scopes, subject, tenant. A call failure with a valid token is a permissions or API-enablement problem. People lose hours re-checking the Admin console for errors that were never about the grant.

Error reference

Symptom	What it means
`unauthorized_client` full guide →	A requested scope is not authorized for this client ID in this tenant — or the client ID / subject is wrong.
`storageQuotaExceeded`	You created a Drive file as the bare service account. Service accounts have zero storage. Impersonate a real user with with_subject and the file lands in their Drive.
`403 insufficientPermissions`	The token was issued, so delegation is fine — the scope you hold is too narrow for the call. Read-only scope attempting a write is the usual case.
`403 accessNotConfigured / SERVICE_DISABLED`	The API is not enabled in the Cloud project that owns the service account. Nothing to do with the Workspace grant.
`invalid_grant`	Clock skew on the calling machine, a deleted or disabled service account, or a revoked key. Check system time first — it is more often that than anything exotic.
`404 on a user's resource`	You are impersonating the wrong subject. The call succeeded as somebody — just not the person whose data you expected.
`Works for one API, fails for another`	Expected. Scopes are granted and fail independently. Verify each API separately rather than assuming one green check covers the rest.
`Worked yesterday, fails today`	Someone edited the grant, a key was rotated, or the subject was suspended. Check the Admin console grant before touching code.

Two habits that prevent most of this

Verify by observation, not by reading

Do not conclude a scope works because it is in the config file. Mint a token and make the call. The same discipline applies to anything downstream — if a script reports success, confirm the effect actually happened rather than trusting the return code.

Keep the scope list in one place

One document listing every scope, which tenants it is authorized in, and what depends on it. Delegation problems are almost always drift between that list and reality, and without the list there is nothing to compare against.

Hand it to someone who has seen it before

We run delegated automation across multiple Workspace tenants in production. If your setup is failing and the error is not on this page, an hour with us is usually enough. $500 per hour.

Get unstuck