Google Workspace has no "approve this app" button for tools like MigrateX. Instead, a super administrator authorises the MigrateX service account once, under domain-wide delegation, and MigrateX then works through Google's APIs on behalf of each user. Nothing is installed; no user signs in.
console.cloud.google.com. Most Workspaces have one automatically; a Workspace whose administrators have never opened the Cloud console may show No organization. Fix: a super administrator signs in at console.cloud.google.com once and accepts the terms — the organization is created for the domain within a few minutes (then IAM & Admin → Settings shows it). Without it, Verify fails on every scope with unauthorized_client.Step by step
- Check the organization existsA super administrator opens
console.cloud.google.com; the project picker at the top should list the organization named after your domain. If it says No organization, accept the terms and wait a few minutes — see the note above. - Press Connect source tenant (or target)On the project Overview. MigrateX shows the client ID and the exact scopes to copy — they depend on your project's scope.
- Open the Google Admin consoleSecurity → Access and data control → API controls → Manage domain-wide delegation → Add new.
- Paste the client ID and the scopesCopy them from MigrateX exactly — the scopes are comma-separated and case-sensitive. Press Authorise.
- Enter a super administrator address in MigrateXIt is used only for directory and admin calls (listing users, Groups, shared drives). Migrations run as each user.
- Press Verify and connectMigrateX tries every scope one by one and shows which work.
- Enter the code from the administrator's inboxMigrateX emails a six-digit code to that super administrator address and only saves the Workspace once it is entered — proof that the person connecting really controls it. Valid for 15 minutes.
Who does what — and what it costs
| Done by | How often | Needs | |
|---|---|---|---|
| Google Cloud project, APIs, service account and its key | MigrateX (the service operator) | Once, for every customer | Nothing to pay — a Google Cloud project and a service account are free |
| Domain-wide delegation of MigrateX's client ID | Your Workspace super administrator, in the Admin console | Once per Workspace (source and target) | No Google Cloud console, no project, no keys, no password shared |
| The confirmation code | The same super administrator | Once per connection | Access to that mailbox |
Licenses. Nothing extra. Every Workspace already has a super administrator, who is an ordinary licensed user of that Workspace — MigrateX uses that existing address and creates no account of its own. The target Workspace needs its normal subscription with a seat for each person who is moving, which it needs anyway; the assessment lists anyone whose target account does not exist yet.
How the access works
MigrateX has one identity for all customers: a service account with a client ID and a private key that never leaves the MigrateX server. When your administrator authorises that client ID in the Admin console, your Workspace agrees that it may act as your users for exactly the listed scopes. From then on, to read a mailbox MigrateX signs a short-lived request — "I am client ID X, acting as aisha@your-domain, for Gmail" — and Google answers with a token valid for one hour for that user. Every call to Gmail, Drive, Calendar, Contacts, Groups and the Admin SDK uses such a token; MigrateX never holds your passwords and keeps no token beyond its hour. Removing the delegation entry ends all access at once.
In a Workspace-to-Workspace move both Workspaces authorise the same client ID, so MigrateX can act as aisha@old-domain on one side and aisha@new-domain on the other and copy user to user: Gmail messages with labels and flags, calendars with recurrence, contacts, Drive files (native Docs stay native) with sharing recreated for matched people; Groups, shared drives and Chat spaces as the administrator; and at cutover the domain itself. Google's API quotas belong to MigrateX's project and are shared fairly between customers by the rate governor.
The scopes and what they are for
| Scope | Used for |
|---|---|
admin.directory.user, admin.directory.domain.readonly, admin.reports.usage.readonly | Users, domains and sizes for the assessment and matching |
gmail.modify, gmail.settings.basic, gmail.settings.sharing | Mail, labels, filters, signatures, vacation, send-as |
contacts, calendar | People contacts and calendars |
drive | Drive files, sharing, shared drives, server-side copy |
admin.directory.group, apps.groups.settings | Groups, members, aliases and settings |
chat.import, chat.spaces, chat.memberships | Chat spaces in import mode |
siteverification | Domain verification during cutover |
drive only, the usual cause is a typo in that one scope or an old delegation entry for the same client ID — edit it rather than adding a second.Things worth knowing
- Drive to Drive copies inside Google (share → copy → unshare); the file never leaves Google.
- Gmail history IDs give MigrateX a true delta: a second pass carries only what changed.
- Revoke at any time by removing the client ID from domain-wide delegation.
- Nothing needs to be created in the customer's Google Cloud console — no project, no API, no service account. Only the organization resource must exist (it appears once a super administrator has signed in there).