# Google Workspace directory sync

Source: https://sig.surf/integrations/google-workspace-directory (Markdown version of the page)

Sig.Surf reads your people from Google Workspace so a signature's name, title and phone number come from the directory instead of being typed in by hand.

## What it does

- Lists users, organizational units and groups from your domain. It never writes to the directory.
- Creates people who join, applies changes to people who stay, and marks people who are no longer in Google as departed.
- Uses organizational unit paths as departments, so you can assign a template to a department.
- Leaves alone people you added by hand and any details an admin edited in Sig.Surf.

## Access it needs

| Scope | Used for |
| --- | --- |
| `admin.directory.user.readonly` | Reading users |
| `admin.directory.group.readonly` | Reading groups and their members. If this scope is not granted, users still sync and groups are skipped. |

A Google Workspace super admin grants access once through domain-wide delegation. See [how deployment is authorized](https://sig.surf/docs/google-workspace-deployment).

## Safety checks

- If Google returns no users, the sync stops without changing anything.
- If a sync would mark more than half of your people, and more than five, as departed, it stops and asks an admin to confirm instead of continuing.

## Limits today

- Profile photos are not copied from Google. Add each person’s photo in Sig.Surf, on their People page or by the person in the employee hub, by uploading an image file (PNG, JPG, GIF or WebP up to 2 MB) or pasting an https image link.
- Custom field mapping is not available.
- As of 2026-11-17, syncs are started by an admin; automatic scheduled syncs are not live yet.
