Setup guide · Google Workspace · Coming soon

Set up Google Workspace accounts for joiners and leavers: step by step

This guide is for two people working together: your Google Workspace super admin, who creates the service account and authorises it in Google Admin, and a company admin in AhlanHamad, who connects it. Follow it in order. Every AhlanHamad label below is the one you will see on screen.

Updated 12 October 2026

1. Before you start

Coming soon. You can create the service account and connect Google Workspace today, and AhlanHamad checks the connection with Google. Suspending leavers, reactivating rehires and creating accounts for new hires stay switched off until we switch them on for your company; until then the Google Workspace page shows only the connection.

Check	What you need
Where it stands	Built, and tested only against a simulated Google Admin API. It hasn't run in a real Workspace yet, so when we switch it on for you, watch the first changes on the Activity tab.
Google Workspace	Your organisation's Google Workspace, and a super admin: only a super admin can authorise domain-wide delegation in Google Admin (Google Admin Help).
A Google Cloud project	Any project your organisation owns, to hold the service account. A new one, for example `ahlanhamad-hr`, keeps it apart from everything else (Google: create a project).
In AhlanHamad	A company admin who can manage settings, to connect Google Workspace and choose the account settings.

Never deleted. AhlanHamad never deletes a Google account and has no setting that would. A leaver's account is suspended; deleting it, and deciding what happens to its mail and files, stays with you in Google Admin.

2. In Google Cloud: create the service account and its key

Sign in to the Google Cloud console with an account of your organisation, and pick (or create) the project from section 1.

Turn on the Admin SDK API (Google's developer pages also call it the Directory API): APIs & Services → Library, search for “Admin SDK”, open it and click Enable. Or open Google's direct link with the project selected (Google: enable APIs).
Create the service account: Menu → IAM & Admin → Service Accounts → Create service account. Name it, for example ahlanhamad-directory, and click Create and continue. It needs no Google Cloud role: skip the optional role and user-access steps and click Done (Google: create access credentials).
Click the new service account's email, open the Keys tab → Add key → Create new key → JSON → Create. A .json file downloads. Keep it safe: Google says it is the only copy of the key, and you paste its whole content into AhlanHamad in section 4 (Google: create and delete keys).
Note the service account's Client ID, a long number: on the service account, click Show advanced settings and copy it under Domain-wide delegation. It is also the client_id inside the JSON file. You need it in section 3.

Can't create a key? Google Cloud organisations created on or after 3 May 2024 block service-account keys by default (the organisation policy iam.disableServiceAccountKeyCreation). An Organization Policy Administrator can exempt this one project (Google: create and delete keys, secure-by-default organisations). AhlanHamad connects with a JSON key; it has no keyless option today.

3. In Google Admin: authorise domain-wide delegation

Domain-wide delegation lets the service account act as one of your admins, limited to the scopes you list. A super admin does this once (Google Admin Help).

Sign in to the Google Admin console as a super admin.
Go to Menu → Security → Access and data control → API controls.
Click Manage Domain Wide Delegation, then Add new.
Client ID: the service account's Client ID from section 2.
OAuth scopes: paste exactly https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.orgunit.readonly (the two scopes, separated by a comma). If your screen asks for one scope per box, add the two separately.
Click Authorize. To check, point at the entry and click View details: both scopes must be listed. Google says changes can take up to 24 hours but usually work sooner; if Connect fails straight after, wait and try again.

Scope	Why AhlanHamad asks for it
`https://www.googleapis.com/auth/admin.directory.user`	Required. Reading your users (to link them to employees), suspending and reactivating linked accounts, and creating accounts for new hires if you switch that on (Directory API scopes).
`https://www.googleapis.com/auth/admin.directory.orgunit.readonly`	Read-only, for one thing: listing your organisational units so you can choose where new accounts go. Without it, everything else works and the picker says to add it.

AhlanHamad asks for nothing else: no groups, no Gmail, no Drive. Once account changes are switched on, the Connection tab shows Domain-wide delegation with the client ID and these exact scopes, so you can compare them with Google Admin.

4. In AhlanHamad: connect Google Workspace

Go to Integrations and open Google Workspace. The card is called Google Workspace Connection.
Primary Domain: your organisation's primary domain, for example company.com.
Admin Email: the email of a super admin. The service account acts as this person (“A super-admin email to impersonate via domain-wide delegation.”). If that admin leaves or loses the role, Google stops accepting the connection, so pick an account your IT team keeps.
Service Account JSON: open the .json file from section 2 in a text editor and paste all of it. It is “Stored encrypted on the server — never shown again and never sent to the browser.”
Click Connect Google Workspace. While it checks, the button says Verifying Connection. AhlanHamad asks Google for a real access token with your delegation; the card then says Connected to Google Workspace with your Primary Domain.
After connecting you can delete the downloaded .json file from your computer. If you ever need to connect again, create a new key.

Until account changes are switched on for your company, the page stays at this connection card: nothing is suspended or created.

5. Account changes (once switched on for your company)

When we switch account changes on, the Google Workspace page gets four tabs: Connection, Account lifecycle, Import and Activity. Its description becomes “Suspends a departed employee's Google account at the end of their last day, reactivates it on rehire, and can create accounts for new hires. Accounts are never deleted.”

First: link the accounts your staff already have

On the Connection tab, check the Domain-wide delegation card against Google Admin and press Test connection. “Google accepted the connection. Waiting changes are running again.” means it works.
Open Import and click Read Google directory. Each Google user is matched to an employee: exact email first, then similar names.
Tick the matches that are right and click Link selected. Nothing is linked until you confirm, and nothing changes in Google. Users with no match (shared mailboxes, service accounts, ex-staff) are left alone.

Then: choose what happens

Open Account lifecycle. Suspend the Google account when an employee leaves decides whether leavers are suspended.
Create Google accounts for new hires is off until you turn it on. If you do, choose the Address pattern (first.last, flast, first or Custom), the organisational units (click Load from Google; this needs the second scope from section 3), and who receives the temporary password under Send the temporary password to (HR or The employee's manager).
Click Save.

When someone leaves: their linked Google account is suspended at the end of their last working day, in your company's time zone. A rehire reactivates it, and a suspension still waiting is cancelled (what suspension does in Google).
New hires (only if switched on): an address from your pattern, with a number added when one is taken (sara.ali2). The temporary password is emailed once; AhlanHamad keeps no copy, and the person changes it at first sign-in.
Activity lists each change: Create account, Suspend, Reactivate, with its status. Needs you means a person must act (the reason is shown); Retry queues it again.
AhlanHamad doesn't touch Google users who aren't linked to an employee, doesn't manage groups, aliases or licences, and doesn't change a profile (title, department) after the account is created.

6. Troubleshooting

What you see	What to do
Please enter your API key or credentials	Fill in all three fields: Primary Domain, Admin Email and Service Account JSON.
Service account JSON is not valid JSON.	Paste the whole file again, from the first `{` to the last `}`, without adding anything.
Service account JSON must include client_email and private_key.	That is not a service-account key file. Create a JSON key on the service account's Keys tab (section 2) and paste it.
Failed to authenticate with Google. Check the service account, domain-wide delegation, and admin email.	Google refused the token. Check, in this order: the Client ID in Google Admin is this service account's; the scopes are exactly the ones in section 3; the Admin Email is an active super admin of this domain; the key wasn't deleted. A new delegation entry can take up to 24 hours; try again later.
Google account changes are paused	Google refused the service account after it worked (delegation removed or narrowed, the admin email suspended or no longer an admin, the key deleted). Fix it in Google Admin or Google Cloud (reconnect with a new key if you deleted it), then press Test connection. Nothing waiting is lost.
Google refused the request (HTTP 403). Check domain-wide delegation for the scopes shown on this page.	The token was issued but Google refused the call: usually the user scope is missing from the delegation entry, or the admin email has no right to manage users. Correct it and press Test connection again.
Google refused the org-unit list. Add the org-unit scope shown on the Connection tab to domain-wide delegation.	Edit the delegation entry in Google Admin and add the second scope from section 3. Nothing else is affected.
… already exists in Google. Link it to this employee if it is theirs.	A new hire's address is taken by an existing user. If it is theirs, click Link existing on the Activity row; if not, choose another pattern and press Retry.

7. Disconnecting

In AhlanHamad, go to Integrations → Google Workspace and click Disconnect Google Workspace. AhlanHamad deletes the stored key and makes no more changes in Google.
AhlanHamad cannot withdraw anything at Google for you. To close the door completely, delete the key on the service account's Keys tab in Google Cloud, and remove the client ID under Manage Domain Wide Delegation in Google Admin.

Accounts already suspended stay suspended; AhlanHamad never deletes or changes them after you disconnect.

Google sources used in this guide

Google Workspace Admin Help: control API access with domain-wide delegation, suspend a user.
Google Workspace developers: create access credentials (service account and key), domain-wide delegation for a service account, Directory API scopes.
Google Cloud: create a project, enable an API, create and delete service account keys, secure-by-default organisations (key creation policy).
Google's menus change from time to time. If a name here doesn't match your screen, the linked page has Google's current wording.

About AhlanHamad × Google Workspace· All integrations