Workspace Sync
← All resources
Guides 15 May 2026 · 9 min read

Domain-wide delegation for read-only directory access: a step-by-step setup

Connect Workspace Sync to your Google Workspace in 15 minutes. The exact Google Cloud and Admin Console steps, the precise OAuth scope, and the errors that show up most often.

This is the most technical part of getting Workspace Sync running. It only happens once. After it’s in place, your directory is connected and the system runs itself.

The whole setup takes about 10–15 minutes the first time, and the result is a tightly-scoped Google Cloud service account that can read your Workspace directory — and nothing else.

If you’ve done a Google Cloud service account integration before, skim. If it’s your first time, follow each step.

What you’re actually setting up

Two things need to exist:

  1. A Google Cloud service account — a non-human Google account, with its own credentials, that our backend uses to authenticate.
  2. Domain-wide delegation — authorisation for that service account to impersonate users in your Workspace, scoped only to one specific permission: reading directory entries.

The “domain-wide delegation” term sounds dramatic. In practice, what we authorise is exactly one thing:

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

That scope lets the service account read user records from your directory. It cannot create users, change users, see emails, read files, or do anything else. It’s the narrowest scope Google offers for directory access.

Prerequisites

  • A Google Cloud account (free to create — if Workspace is set up, you already have one).
  • A user account with super admin privileges in your Google Workspace.
  • About 15 minutes.

Step 1 — Create a Google Cloud project

  1. Go to console.cloud.google.com.
  2. In the top bar, click the project selector (it shows the current project name or “Select a project”).
  3. Click New project.
  4. Name it something obvious like workspace-sync-directory. The name only affects what you see in the console.
  5. Leave the organisation as your default Workspace organisation. Don’t change the location.
  6. Click Create.

Wait about 10 seconds for the project to be created, then make sure it’s selected in the top bar.

Step 2 — Enable the Admin SDK API

The Admin SDK is what lets external services read Workspace directory data. It’s not enabled by default.

  1. In the left sidebar, go to APIs & Services → Library.
  2. Search for Admin SDK API.
  3. Click the result, then click Enable.

A few seconds. Once enabled, it shows “API enabled” with a green check.

Step 3 — Create a service account

  1. In the left sidebar, go to IAM & Admin → Service Accounts.
  2. Click Create service account at the top.
  3. Service account details:
    • Name: workspace-sync-service (or whatever’s recognisable)
    • ID: auto-fills based on name — that’s fine
    • Description: “Read-only directory access for Workspace Sync”
  4. Click Create and continue.
  5. Grant access step: leave blank. We don’t need project-level roles. Click Continue.
  6. Grant users access step: leave blank too. Click Done.

You’ll land back on the service accounts list. Click the service account you just created to open its details.

Step 4 — Generate a JSON key

This is the credential file the sync product will use to authenticate.

  1. On the service account detail page, go to the Keys tab.
  2. Click Add Key → Create new key.
  3. Select JSON, then Create.
  4. A JSON file downloads to your computer.

Keep this file safe. Anyone with it can authenticate as this service account. Treat it like a password.

Step 5 — Note the Client ID

You’ll need the service account’s numeric Client ID for the next step.

  1. Still on the service account page, click the Details tab.
  2. Find the Unique ID field. Copy it — it’s a long number.

You can also find this inside the JSON key file under the client_id field.

Step 6 — Enable domain-wide delegation

The critical step. You’re telling Workspace: “this specific service account is allowed to impersonate users, but only for this specific scope.”

  1. Open admin.google.com and sign in as a Workspace super admin.

  2. Go to Security → Access and data control → API Controls.

  3. Click Manage Domain Wide Delegation at the bottom of the page.

  4. Click Add new.

  5. Client ID: paste the Unique ID from Step 5.

  6. OAuth scopes: paste exactly this:

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

    No other scopes. Just this one.

  7. Click Authorize.

You’ll see the new entry in the list with the client ID and the scope you authorised.

The change takes 2–5 minutes to propagate across Google’s systems. It’s safe to continue, but if the first sync fails right after this step, wait five minutes and retry.

Step 7 — Add credentials to Workspace Sync

  1. In the Workspace Sync admin dashboard, go to Settings.
  2. Find the Google Workspace credentials section.
  3. Fill in:
    • Workspace admin email: the email of a super admin in your Workspace. The service account impersonates this user when reading the directory. The read happens as if a super admin were doing it, but only the scope you authorised in Step 6, which is read-only directory access.
    • Service account credentials (JSON): open the JSON key file from Step 4, copy the entire content, paste it into the field.
  4. Click Save credentials.

The credentials are immediately stored in our secure vault, encrypted, and the form field is cleared. They cannot be read back — not even by our support team. This is by design: if your credentials are ever suspected to be compromised, you regenerate them in Google Cloud and re-paste them here. There’s no “view current credentials” button anywhere.

Step 8 — Trigger the first sync

  1. Go to Contacts in the admin dashboard.
  2. Click Sync from Google Workspace.

The first sync takes 5–30 seconds depending on directory size. Contacts appear in the list as they’re synced. If everything’s wired correctly, every user in your Workspace shows up.

After the first sync, automatic syncing runs every 6 hours in the background — you don’t need to trigger it again.

Troubleshooting

A few errors come up regularly.

”Service account does not have access to the Workspace data”

The domain-wide delegation step (Step 6) didn’t take, or hasn’t propagated yet. Wait 5 minutes and retry. If it’s still failing after 10 minutes, go back to Admin Console → Domain Wide Delegation and verify the Client ID and scope are exactly as in Step 6.

”The admin email impersonation failed”

The email in Step 7 isn’t a super admin, or doesn’t exist. Verify in Admin Console → Users that the email is correct and the user has the Super Admin role.

”Admin SDK API has not been used”

You skipped or didn’t successfully complete Step 2. Go back to Google Cloud Console → APIs & Services → Library, search Admin SDK API, and click Enable.

Sync runs but no contacts appear

Two possible causes:

  • Your Workspace directory is empty, or all users are excluded. Verify in Admin Console → Users that you have users with active status.
  • The Admin SDK only returns active users by default. Suspended or deleted users won’t appear.

Some contacts appear but not all

A per-user setting in Workspace is excluding them from the directory. In Admin Console → Users → user details → Profile, check Show this user in the directory. Users with this off won’t be returned by the directory API.

Security model — what the service account can and cannot do

Worth being explicit:

What it CAN do:

  • Read user records from your Workspace directory (name, email, phone, photo, title, department, etc.)

What it CANNOT do:

  • Create, edit, or delete users
  • Read any user’s email, calendar, files, or any other Workspace data
  • Make changes to Workspace settings
  • Access groups, devices, mobile apps, or any other admin function
  • Authenticate to anything other than the Admin SDK directory endpoints

The single scope admin.directory.user.readonly is genuinely as narrow as it gets. Read-only, directory-only, user-records-only. This is verifiable in the OAuth consent screen, and every directory call we make on your behalf is audited in Workspace’s standard admin audit logs.

What’s next

Once setup is done, the directory syncs every 6 hours and the system runs itself. Two follow-up things to think about:

  • Field configuration. By default we expose name, email, phone, photo, title, and department to the mobile app. If you want to hide specific fields (e.g., internal extension numbers, manager hierarchy), go to Fields in the admin dashboard. This is per-organization — your choices apply across every employee.
  • Inviting employees. Each employee installs the mobile app, signs in with their work Google account, and the directory becomes available. No per-employee admin step.

If you hit a setup error not covered above, contact us. Setup is the one part of this product that occasionally needs hand-holding — we’d rather get you over it than have you give up.

Ready to give your team an always-current directory?

Workspace Sync delivers your Google Workspace directory to every employee's phone — set up in minutes, free for teams up to 10 users.

See pricing Contact us