Setup guide

Create, read, patch, suspend, delete and undelete user accounts, move them between org units, and manage aliases.

↳ For audit-only or drift-report runs grant https://www.googleapis.com/auth/admin.directory.user.readonly instead; it cannot mutate the directory.

List and create groups, and read group settings when reconciling a roster against target groups.

↳ Use https://www.googleapis.com/auth/admin.directory.group.readonly when the skill only reports on group membership.

Check membership with groups.hasMember and add or remove members idempotently.

↳ https://www.googleapis.com/auth/admin.directory.group.member.readonly covers the hasMember and members.list checks without allowing writes.

List the org unit tree and create missing org units parent-first before moving accounts into them.

↳ https://www.googleapis.com/auth/admin.directory.orgunit.readonly is enough when all target OUs already exist.

Call users.signOut to terminate all web and device sessions and reset sign-in cookies during offboarding.

Read customers.get to resolve the my_customer alias into the literal C0xxxxxxx customer ID that the Enterprise License Manager API demands.

↳ This is already the read-only variant; the writable https://www.googleapis.com/auth/admin.directory.customer scope is never needed by this skill.

List licence assignments per SKU, assign licences to new users, move users between SKUs and revoke seats.

↳ https://www.googleapis.com/auth/apps.licensing.user.readonly allows seat reporting without changing any assignment.

The impersonated subject inherits this role; it is what actually authorizes directory writes and licence changes, and it is required to create the domain-wide delegation entry in the first place.

↳ For user and group work only, a delegated account holding the prebuilt User Management Admin plus Groups Admin roles is usually sufficient; the Enterprise License Manager API is only reliably callable as a Super Admin.

Cause: The service account's numeric client ID is not present in Manage Domain Wide Delegation, or the exact scope you requested in code is missing from that entry. The delegation scope list is an allow-list, not a hint.

Fix: At admin.google.com/ac/owl/domainwidedelegation edit the entry for the 21-digit Client ID and paste every scope the code requests, comma-separated with no spaces. Wait a few minutes and retry; propagation can take up to 24 hours.

Cause: HTTP 403 with reason 'forbidden'. Either no delegation subject was set (the service account is calling as itself), or the impersonated user is not an administrator, or the account lacks the specific privilege for that call.

Fix: Call .with_subject(GOOGLE_WORKSPACE_ADMIN_EMAIL) on the credentials, and confirm at admin.google.com/ac/roles that the impersonated mailbox holds Super Admin (or at least User Management Admin and Groups Admin).

Cause: HTTP 403 with status ACCESS_TOKEN_SCOPE_INSUFFICIENT. The minted token does not carry the scope this endpoint requires — commonly calling users.signOut with only admin.directory.user, or a licensing endpoint without apps.licensing.

Fix: Add the exact scope to the SCOPES list in code AND to the Admin console delegation entry, then discard any cached credential object so a new token is minted.

Cause: HTTP 403 with reason SERVICE_DISABLED. The API is not enabled on the Cloud project that owns the service account.

Fix: Enable admin.googleapis.com (and licensing.googleapis.com for licence work) on that exact project ID, then wait a minute and retry.

Cause: The private key in the JSON file no longer matches a key on the service account (it was deleted or rotated), or the local clock has drifted far enough to invalidate the assertion.

Fix: Generate a fresh JSON key in the Keys tab and replace the credential, and confirm the host clock is NTP-synchronised.

Cause: HTTP 404 with reason 'notFound'. The userKey does not resolve — a typo, a user in a different tenant, or a just-created account that has not finished propagating.

Fix: Confirm the address with users.list, and after a create retry the first follow-up call on 404 with backoff for roughly 60 seconds before failing.

Cause: HTTP 409 with reason 'duplicate' on users.insert or members.insert. The account or membership is already present — usually a re-run of the same batch.

Fix: Treat 409 as convergence rather than failure: fetch the existing resource and fall through to the update path. Idempotent runs should never abort on this.

Cause: HTTP 403 (or 429 rateLimitExceeded) after exceeding roughly 2,400 queries per minute per user, more than 10 user creations per second per domain, or more than 1 org-unit write per second per customer.

Fix: Retry with exponential backoff starting at 1 second and doubling to 16 seconds with jitter, and lower write concurrency. The per-account 429 limit cannot be raised in the Cloud console.