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. The dashboard has the same seven steps: open Settings → Connection and expand Setup guide. Each step has a Mark done & continue button, and I already have a JSON key jumps straight to the last one.

Before you begin

You need:

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

Sign in to Workspace Sync with that super admin account before you upload the key. Workspace Sync reads your directory on behalf of the person who saves the key. If that person is not a super admin, the first sync fails. The first person from your company to sign in becomes the admin, so the simplest path is for the super admin to sign up and do the whole setup. If someone who isn’t a super admin signed in first, the super admin signs in as well and chooses Join as admin. Workspace Sync checks with Google that they are a super admin, adds them as a second admin, and connects with their account; they can paste the JSON key there too. This works until the first sync has succeeded.

Workspace Sync needs this one permission:

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

It lets Workspace Sync read the people in your directory: names, emails, phones, titles, departments and photos. It cannot write.

Create a Google Cloud project

In the Google Cloud Console, create a new project or select an existing one. A name like workspace-sync keeps it easy to find and to revoke later.

Enable the Admin SDK API

Go to APIs & Services → Library, search for Admin SDK API, open it and press Enable. Syncing does not work without it.

Create a service account

Go to APIs & Services → Credentials → Create credentials → Service account. Pick a name, for example workspace-sync, and a service account ID, then press Create and continue. The optional access steps can be skipped.

Copy the service account’s Client ID

Go to IAM & Admin → Service Accounts and open your service account. On the Details tab, expand Advanced settings and copy the Client ID, a 21-digit number. You’ll paste it in the next step.

Authorise the service account in Google Workspace

This must be done by a super admin, in the Google Admin console at admin.google.com.

1. Open Security → Access and data control → API controls → Manage Domain-wide Delegation.
2. Press Add new.
3. Client ID: paste the Client ID from the previous step.
4. OAuth scopes: paste the required scope:

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

5. Press Authorise.

Optional: add a second scope to show your company name (from your Workspace billing profile) on each contact in the mobile app. Without it, the Organization field shows only what is filled in per person in Google Workspace. Google’s field accepts both scopes comma-separated.

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

Give Google two to five minutes to apply the change, occasionally up to 30.

Download the JSON key

Back in the Google Cloud Console, open your service account → Keys → Add key → Create new key → JSON. The file downloads automatically. Keep it private.

A key can only be downloaded once. If you lose the file, create a new key. If Google says Service account key creation is disabled, an organisation policy blocks it; the dashboard’s Setup guide shows the gcloud commands to allow it for this project.

Upload the JSON key

1. Make sure you are signed in to app.workspace-sync.com as the super admin.
2. In Settings → Connection, step 7 of the Setup guide: paste the contents of the JSON file into Service Account Credentials (JSON), or upload the file.
3. Press Save Credentials.

Workspace Sync checks the connection with Google and runs the first sync straight away. When it works, you see Connected! Synced N contacts. and land on Contacts. Credentials are encrypted and cannot be viewed after saving.

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