Connect Google Workspace

Workspace Sync reads your directory through a service account with domain-wide delegation and one read-only permission. Nothing is installed in your Google Workspace and nothing can be changed there. You’ll create the account in Google Cloud, authorise it in Google Admin, and paste its key into Workspace Sync.

Check you have what you need

Before you start, make sure you have:

• A Google Workspace super admin account. Only a super admin can authorise the connection in the Google Admin console.
• Access to Google Cloud Console at console.cloud.google.com with the same account, to create the service account.
• About ten minutes, plus a short wait of two to five minutes for Google to apply the authorisation.

Workspace Sync will only ever ask for this one permission:

https://www.googleapis.com/auth/admin.directory.user.readonly

It lets Workspace Sync read people, their names, emails, phones, titles, departments and photos. It cannot write.

Create a service account and enable the Admin SDK

All of this happens in Google Cloud Console.

1. Create a new project, or pick an existing one. A name like workspace-sync keeps it easy to find and to revoke later.
2. Go to APIs & Services → Library, search for Admin SDK API, open it and press Enable. Syncing does not work without it.
3. Go to APIs & Services → Credentials → Create Credentials → Service account. Give it a name, press Create and continue, skip the optional access step, press Done.
4. Open the service account, then the Details tab. Under Advanced settings, note the Client ID. You’ll paste it into Google Admin in the next step.
5. Open the Keys tab → Add key → Create new key → JSON → Create. The key file downloads. Keep it private; you’ll paste its contents into Workspace Sync in step four.

If your Google Cloud organisation restricts who may be granted access (the iam.allowedPolicyMemberDomains policy), an organisation administrator may need to allow it before the key can be created.

Authorise domain-wide delegation

This is the step that lets the service account read your directory. It must be done by a super admin, in the Google Admin console.

1. Go to admin.google.com.
2. Open Security → Access and data control → API controls.
3. Press Manage Domain Wide Delegation, then Add new.
4. Paste the Client ID from the previous step.
5. Paste exactly this into OAuth scopes:

https://www.googleapis.com/auth/admin.directory.user.readonly

6. Press Authorise.

Give Google two to five minutes to apply the change before you run the first sync.

Add the key to Workspace Sync and run the first sync

1. Sign in to the dashboard at app.workspace-sync.com and open Settings.
2. Enter the Workspace admin email: the address of a Google Workspace super admin, for example admin@yourcompany.com. The service account acts on behalf of this person.
3. Paste the entire contents of the JSON key file into the credentials field and save.
4. Open Contacts and press Sync now. Your people appear within a minute or so.

The key is encrypted on save and cannot be read back, by you or by us. The field clears; to change the key later, paste a new one.

New people arrive with App access off, so nothing is billed and nobody can sign in until you decide. Next: App access and directory visibility. If the sync did not complete, see Fix “Sync failed”.