Google Workspace migration setup

• You are a Google Workspace super-admin on the domain you want to migrate.
• You are a workspace admin of the Cirrux workspace that will receive the migrated data.
• Your Cirrux user account has the workspace_migration_v1 tag enabled. Cirrux support will set this for you during onboarding.

The Cirrux Google Workspace app requests the following OAuth scopes:

• userinfo.email and userinfo.profile— to identify which admin authorized the connection.
• admin.directory.user.readonly— to list the users in your Workspace so you can map them to Cirrux members.
• admin.directory.customer.readonly— to read your Workspace organization name and primary domain for display in the Cirrux admin panel.

In a later phase, we will request additional read-only scopes for Gmail, Calendar, and Contacts so individual mailboxes can be migrated. Those scopes will only be requested when you initiate a migration run.

Google Workspace restricts third-party app access by default. Before Cirrux can call the Directory API on your behalf, you must explicitly trust the Cirrux OAuth client in your Workspace admin console.

1. Open admin.google.com and sign in as a super-admin.
2. Navigate to Security → Access and data control → API controls.
3. Scroll to App access control and click Manage Third-Party App Access.
4. Click Add app → OAuth App Name Or Client ID.
5. Paste the Cirrux OAuth client ID (provided by your Cirrux contact) and search.
6. Select the Cirrux app from the results, then Continue.
7. Choose Trusted: Can access all Google services. (If you prefer Limited, tick all the scopes listed above — an incomplete scope list will block the connection.)
8. Apply to your entire domain, review, and confirm.

Changes propagate in a few minutes but can take up to 24 hours in rare cases.

1. In Cirrux, open Settings → Workspace → Admin.
2. Find the Google Workspace card and click Connect Google Workspace.
3. Sign in as the Google Workspace super-admin you used in step 1 and approve the requested scopes.
4. You’ll be redirected back to the admin page. Within a few seconds, the card should refresh to show your Workspace domain, organization name, and total user count.

A healthy connection shows your domain (e.g. acme.com), the org name pulled from the Workspace directory, and the total Workspace user count. If the user count never populates, see troubleshooting below.

You’re seeing the “You don’t have access to this app until an administrator reviews and configures access” screen during step 2.

This means the Workspace admin allowlist step (step 1) hasn’t taken effect for the scopes Cirrux is requesting.

• Confirm the Cirrux app is listed under API controls → Manage Third-Party App Access and its access is Trusted.
• If you chose Limited, re-edit and tick every scope listed above, including admin.directory.user.readonly.
• Wait 5–10 minutes for propagation, then sign out of Google completely (or use an incognito window) and retry the connection.

The connection succeeds but the card stays empty after a minute or more.

• The most common cause is that your trusted-app access excludes the Directory API. Re-check step 1 and make sure admin.directory.user.readonly is explicitly authorized (or use Trusted: Can access all Google services).
• Try disconnecting and reconnecting from the Cirrux admin card.
• If it still doesn’t resolve, share the connection UUID (shown in the URL of the admin page) with your Cirrux contact so we can inspect server logs.

You’re a Cirrux workspace admin but the card doesn’t render in your admin settings.

• The feature is gated on the workspace_migration_v1 user tag. Ask your Cirrux contact to enable it for your user.
• Confirm you are a member of the workspace with the adminrole — not just a regular member.

In this phase, Cirrux only reads the user list and basic organization metadata from your Workspace. No mailbox, calendar, or contact data is accessed yet. The admin OAuth token is encrypted at rest in Cirrux’s database and only used to call the Directory API.

You can disconnect at any time from the Cirrux admin card. Disconnecting clears the stored token and revokes the refresh token with Google.