> For the complete documentation index, see [llms.txt](https://docs.siit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.siit.io/integrations/iam/google-workspace.md).

# Google Workspace

Connect Google Workspace to Siit to sync your users and groups, and power group management actions from every request and workflow.

<figure><img src="https://451675063-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fz9xmM8V3atukfr2XaElR%2Fuploads%2FtR8w3wnV2cwYmvBrTJCB%2FSiit_Google.jpg?alt=media&amp;token=3414899a-cfbe-4b4d-8ea2-33730836f762" alt=""><figcaption></figcaption></figure>

Connect Google Workspace to manage groups directly from any request. Add or remove users from Google Groups in the side panel, in workflows, or via IT Agent, and feed Day-1 onboarding flows from your HRIS-driven org structure.

### What you get

* **Live directory** — Google Workspace users sync into Siit with email, name, org unit, and group memberships.
* **People fields source** — sync department, manager, job title, start date, location, and phone number into People fields, and set Google Workspace as the Priority source for any of them in **Settings → Context management → People fields**.
* **Group management actions** — add or remove users from Google Groups directly from request side panels, workflows, and IT Agent playbooks.
* **Account recovery actions** — set a temporary password, or hand a locked-out employee one backup verification code, without the value ever appearing in the conversation.
* **Audit trail** — every group change triggered from Siit is logged on the request timeline.
* **Source for onboarding and access requests** — pair Google with an HRIS to run Day-1 flows that place new hires into the right distribution lists and access groups automatically.

> **Scope note** — Siit's Google Workspace integration focuses on **directory sync, group management and account recovery**. The rest of the user lifecycle (create, suspend, delete) is not currently exposed as a native Siit action for Google Workspace — if you need those, pair Google Workspace with Okta, Entra ID, or JumpCloud, or use the IT Agent with custom webhooks.

### What syncs from Google Workspace

| Category      | Fields                                                             |
| ------------- | ------------------------------------------------------------------ |
| Identity      | Full name, primary email, aliases, Google user ID                  |
| Org context   | Organizational unit, job title (if set in Directory)               |
| Groups        | Group memberships, group ownership                                 |
| People fields | Department, manager, job title, start date, location, phone number |

Work email (the primary Google email) is the canonical identifier.

Google Workspace can be set as the **Priority source** for any People field it provides, in **Settings → Context management → People fields**, alongside your HRIS. If more than one system feeds the same field, the priority source wins.

### Actions available

* **Google → Add user to group** — add a user to a Google Group. Available in side panel, workflows, and IT Agent.
* **Google → Remove user from group** — remove a user from a Google Group. Available in side panel, workflows, and IT Agent.
* **Set a temporary password** — set a temporary password on the user's account, generated by Siit or typed by you. They must change it at their next sign-in. Available in side panel, workflows, and IT Agent.
* **Issue a backup verification code** — hand the user one backup verification code so they can pass the second step without their phone or security key. Available in side panel, request workflows, and IT Agent.
* **Invalidate backup verification codes** — stop every backup code of the account from working. Run it once the user has enrolled a new device. Available in side panel, workflows, and IT Agent.

Every action can be gated behind approvals when used in workflows or IT Agent playbooks.

#### Temporary passwords and backup codes

Both hand over a value only the employee should read, so Siit treats them as [secret codes](/request-management/secret-codes.md): send the value privately to the requester, or reveal it to yourself once. Siit never writes it to the request thread.

* Issuing a backup verification code **generates a fresh set at Google**, so every backup code the user already had stops working. Siit hands over one code from the new set and never shows the others.
* The code does not expire on its own. Siit stops showing it after your workspace secret code lifetime, but the code itself works once, until it is used or you invalidate the set.
* A backup code only covers the second step. The user still needs their password.
* Under an "Only security key" 2-Step Verification policy, Google accepts backup codes during its grace period only.

**When an action can't run**

* **The admin who connected Google Workspace** cannot have their password reset or a backup code issued — that would risk locking Siit out of your tenant.
* A **suspended user**, or one **not enrolled in 2-Step Verification**, cannot be issued a backup code. A user whose enrolment has not synced yet is reported as still syncing; retry after the next sync.
* If Google times out or errors partway through generating the set, Siit reports the run as unfinished and invalidates nothing. Check the user in the Google Admin console before you retry.

### Before you connect

* You'll need a **Google Workspace Super Admin** account to grant the initial OAuth consent. Consent is granted once at the workspace level.
* Decide which admin account will own the connection. The integration continues to work after individual admins change, but re-authorization requires a Super Admin.
* Choose whether Siit should have **read-only directory access**, or also the **group management** and **user security** scopes. Without the group management scope, add/remove actions won't be available; without the user security scope, the backup verification code actions won't be offered.

### Connect Google Workspace

1. In Siit, go to **Settings → Workspace → Integration library**.
2. Find **Google Workspace** in the IAM section and click **Connect**.
3. You'll be redirected to Google to sign in. Sign in with a Super Admin account.
4. Review the requested OAuth scopes:
   * Read directory (users, org units, groups and memberships)
   * Optional: manage group memberships — required for add / remove actions
   * Optional: manage user security (`https://www.googleapis.com/auth/admin.directory.user.security`) — required for **Issue a backup verification code** and **Invalidate backup verification codes**
5. Accept the consent and you'll be redirected back to Siit.
6. Siit runs an initial import of users and groups (can take a few minutes for large workspaces).
7. Review the imported data and click **Finish setup**.

> **Tip** — If your Google Workspace has **app access control** restrictions, a Super Admin may need to explicitly allow Siit in Security → API controls → App access control → Manage third-party app access. Otherwise the OAuth flow will fail silently or with a "restricted" message.

### After the connection

* **Check your People list** — confirm users imported correctly. The count should match Directory users (excluding suspended, unless you opted to include them).
* **Scope the groups** — by default all groups are synced. In **Settings → Workspace → Integration library → Google Workspace**, you can scope to specific groups or org units if you don't want the entire directory tree.
* **Try an action from a request** — open any request, and use the side panel Apps section to add/remove the requester from a Google Group.
* **Build a workflow** — a good first workflow: an access request that adds the requester to a group after manager approval.

### Sync frequency

Google Workspace data refreshes automatically every few hours. Actions run on demand, immediately, when triggered from Siit.

To pull the directory in straight away, open the **⋯** menu on the Google Workspace card in **Settings → Workspace → Integration library** and pick **Synchronize**. The action hides itself while a sync is running and for 15 minutes after the last one.

### Common workflows

**Access request.** *Trigger: Request submitted (service = "Request group access"). Actions: manager approval → Google add to group → DM requester.*

**Day-1 onboarding (with HRIS).** *Trigger: Start date. Actions: Google add to onboarding@ group and dept-specific groups → notify manager.*

**Offboarding on end date.** *Trigger: End date. Actions: Google remove from all groups → create equipment pickup request → DM manager.*

**Project access provisioning.** *Trigger: Request submitted with form value Project = "Phoenix". Action: Google add to phoenix-team@ group.*

### Troubleshooting

**Connection fails with "app not authorized".** Super Admin hasn't allowed Siit in Google's third-party app access control. Ask a Super Admin to approve Siit in Security → API controls → App access control.

**Users missing from Siit.** Check whether suspended users are excluded — by default they are. Adjust the filter in **Settings → Workspace → Integration library → Google Workspace**.

**Add to group action fails.** The OAuth scope for group management wasn't granted at install time. Re-authorize the connection and accept the group management scope.

**The backup verification code actions aren't offered.** The user security scope wasn't granted at install time. Re-authorize the connection and accept it. Check too that the user is enrolled in 2-Step Verification — the actions hide themselves for anyone who isn't.

**Group isn't visible as an option.** The group may be scoped out. Check the group scope setting in **Settings → Workspace → Integration library → Google Workspace**, or ensure it's a Google Group (not a shared label or team drive).

**A user isn't in the group after the action ran.** Check the request timeline — if the action succeeded, Google may be propagating the change (some distribution groups take a minute). If it failed, the error is shown inline.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.siit.io/integrations/iam/google-workspace.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.