cirrux

Authorize Cirrux for domain-wide delegation

To migrate your Google Workspace users in bulk, Cirrux reads each user’s Gmail, Calendar, and Contacts using a single service account that impersonateseach user via Google’s domain-wide delegation. This is a one-time authorization a super-admin performs in the Google admin console.

If you installed Cirrux from the Google Workspace Marketplace, this is already authorized automatically and you can skip this guide. These steps are only needed when you authorize Cirrux manually.

What you’ll need

The Cirrux service account Client ID

Domain-wide delegation is granted to this numeric OAuth client ID. It is the same for every domain:

104842372543332532355

Use the numeric Client ID exactly as shown — not the service account’s email address.

The required OAuth scopes

Authorize all fourscopes below. Google requires every requested scope to be present — a partial list is rejected the same way as no authorization at all. Paste them as a single comma-separated value:

https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/contacts.readonly
  • userinfo.email— identify the impersonated user.
  • gmail.readonly— read email and labels.
  • calendar.readonly— read calendars and events.
  • contacts.readonly— read contacts.

Authorize in your admin console

Add the delegation

  1. Open admin.google.com and sign in as a super-admin.
  2. Navigate to Security → Access and data control → API controls.
  3. Under Domain-wide delegation, click Manage Domain Wide Delegation → Add new.
  4. In Client ID, paste 104842372543332532355.
  5. In OAuth scopes, paste the comma-separated scope list above.
  6. Click Authorize.

Wait for propagation, then retry

Delegation changes are not instant — a freshly added grant typically takes a few minutes (and rarely up to 24 hours) to take effect. After authorizing, return to Cirrux and retry the migration.

Troubleshooting

unauthorized_client / the import keeps disconnecting

The migration flips back to disconnected as soon as it tries to read a mailbox. This is almost always the delegation not being in effect yet:

  • Confirm you authorized in the same domain you’re migrating.
  • Confirm all fourscopes are present and spelled exactly as above — a missing or mistyped scope produces the same error.
  • Confirm the entry uses the numeric Client ID (104842372543332532355), not an email address.
  • Wait a few minutes for propagation and retry.
HelpPrivacyTermsSustainability