How VaultMe authentication works

VaultMe reaches a source or a destination only through a connection established to it. This article explains how those connections work as a technical mechanism, rather than how to set one up.

Why does VaultMe need a connection?

A connection is the channel VaultMe establishes to a user account in order to read its content as a source or write content into it as a destination. It is also the only channel VaultMe has. There is no agent to install on a laptop or a server, no browser extension, no separate route into a provider's systems, and no stored password VaultMe could fall back on when a connection stops working. Everything VaultMe can see or do on either side of a migration, it does through connections that were established for that migration.

Today those connections are established to user accounts. Shared drives, shared mailboxes, and other kinds of resources are migrated as well, but they are not connected in their own right: a shared drive is reached through a connected user account that has access to it, and a Microsoft 365 shared mailbox is converted into a regular user account first.

Both sides need their own connection, and both need it for the whole life of the migration. The source has to be connected before VaultMe can read anything out of it, and the destination has to be connected before VaultMe can write anything into it. That holds at every stage: the pre-migration scan looks at the connected accounts, the initial run reads and writes through them, and every sync-up migration (delta migration) afterwards needs both sides connected again. Without a live connection there is nothing to scan, nothing to read, and nowhere to write.

Access also always begins on the customer's side. VaultMe gains access to an account or an environment only when someone connects it — an admin connecting an environment, or an account holder approving access to their own account. VaultMe cannot start that step itself, cannot reach anything that was never connected, and holds no standing access that exists outside a connection.

How access fits into the rest of a migration run is covered in "How the VaultMe platform works". Establishing a connection is preparation work rather than something that happens during a run; which method each side uses, who has to act, and what to line up beforehand are covered in "Choosing a connection method".

What does a connection actually consist of?

Connecting an account happens on the provider's own pages, not inside VaultMe. The person doing it signs in with the provider — Google or Microsoft, for accounts hosted there — and approves the access VaultMe asks for. The password is entered on the provider's sign-in page and goes no further: VaultMe does not request, receive, or store passwords for accounts connected this way.

What VaultMe receives instead is a token issued by the provider. Where providers support it, this exchange uses OAuth 2.0, the standard behind the "Sign in with Google" and "Sign in with Microsoft" flows. A token is not a password and cannot be used like one. It is a credential the provider created for one specific connection, it stands for the permissions that were approved at that moment, and the provider decides how long it remains valid. Three properties of that token matter:

• Scoped to the connection it was issued for. The token carries the permissions approved for the account or environment that was connected, and nothing wider. How wide that is depends on which connection method was used.
• A provider-defined lifetime. The provider, not VaultMe, sets how long the token lasts. Once it expires, the provider stops honoring it and VaultMe loses access until the account is connected again. An expired token is indistinguishable from any other lost connection and is handled the same way — see "What happens if a connection drops?".
• Revocable at any time. Access granted through the provider can be withdrawn through the provider. An account holder, or an admin over the environment, can revoke VaultMe's access without involving VaultMe at all, and it stops working immediately.

The exception is providers that offer no sign-in of this kind. An IMAP-compatible mail system has no consent step and no token to issue, so a connection to one is made with the credentials that protocol requires, supplied when the mailbox is connected. This is the exception rather than the pattern: wherever a provider supports token-based access, that is what VaultMe uses.

What VaultMe stores from a connection, and how tokens differ from passwords in that respect, is covered in "What data VaultMe processes during migration".

What permissions does a connection carry?

A connection carries permissions, and VaultMe asks for the minimum set that the account's role in the migration requires. Role here means which side of the migration the account sits on, and it decides the shape of the request:

• A source connection needs read access. VaultMe reads content out of the source and copies it; it does not write to the source, delete from it, or reorganize it, so nothing beyond reading is requested.
• A destination connection needs read and write access. Write access is the obvious half, since the copies have to be created there. Read access is needed because VaultMe has to see what the destination already holds in order to place content sensibly — for example, to match migrated content into folders and labels that exist there already.

The exact set can also depend on the provider pair, because some source and destination combinations need slightly more than others. The principle does not change: VaultMe requests what the migration requires and stops there.

Whatever the set is, it has to be granted in full for the role the account is connected in. If part of it is missing, VaultMe may be unable to reach some content types, or unable to start the migration at all. Some providers let the person connecting approve part of the requested set and decline the rest; where that choice appears, the full set should be approved, because a partial grant is exactly what produces those gaps.

This is worth attention because a connection with the wrong permissions does not look wrong. The sign-in succeeded, the account shows as connected, and the shortfall is invisible from the outside. Two situations produce it: an account connected in the wrong role — a source connection used for an account that is meant to be a destination, so it ends up with read access where read and write is needed — and an approval that covered only part of what VaultMe asked for. Catching both is what the pre-migration scan is for: it validates access before anything is migrated, and it is described in "How VaultMe works". That is also the argument for connecting accounts and checking them well before migration day. What to watch for while connecting, and how a shortfall is reported and cleared once it is found, is covered in "Connecting and adding user accounts".

How do the two connection methods differ?

VaultMe supports two connection methods, and they produce the same kind of channel. What differs is who grants the access and how wide the grant is; once a connection exists, reading and writing work identically through either one.

• Connection using admin authorization. An admin connects an entire environment — a Google Workspace organization or a Microsoft 365 tenant — once. From that single grant, VaultMe can discover the user accounts in that environment and reach the ones selected for migration without any of them being connected individually, by acting on behalf of each selected account under the environment-level access. Approval is all or nothing with both providers: the admin approves the complete set VaultMe requests, with no per-permission picking at connection time.

  Because this method connects an environment, it exists only where there is one to connect. Discovery surfaces user accounts; other resources in the environment, such as shared drives, are still reached through a connected user account that has access to them.

• Connection using resource-level authorization. Each account is connected on its own, with the grant scoped to that one account and limited to what its role in the migration needs. The account holder normally provides it by signing in as themselves, or an admin does it on their behalf using credentials collected for that purpose. Selective approval is possible with some providers on this path, which is where a partial grant tends to appear.

  This is the only way to connect personal accounts and IMAP-compatible mail systems, since neither has an environment behind it, and it is the fallback wherever an environment-level grant is not available.

The breadth of a grant is not the breadth of what VaultMe touches. An environment-level grant could technically reach every account and every item in that environment, but VaultMe reads and writes only the accounts and content inside the configured migration scope — anything outside it is not read, indexed, or migrated. That boundary comes from VaultMe's own logic and the scope the admin configured, not from the size of the grant, and it is the usual concern when someone is asked to approve environment-wide access; the detail is in "What data VaultMe processes during migration".

Which method is available on each side, what each one costs in practice, and how each is actually established are covered in "Choosing a connection method".

What can VaultMe reach through a connection?

A connection is a narrow channel, and three limits define what comes through it:

• Only what was connected. VaultMe sees the account or environment that was connected and nothing sitting beside it. Another account in the same organization is reachable only if the environment holding it was connected and that account was selected for migration.
• Only the content types in the migration scope. Email, files, calendars, and contacts are each in scope or not, and types that are not in scope are not read, indexed, or migrated, even where the granted permissions would technically allow it.
• Only what the account exposes in the cloud. VaultMe talks to the provider's service, so it sees what that service holds for the connected account, and nothing that lives anywhere else.

That last limit is the one that, in some scenarios, comes as a surprise to end users, because a single device blends several clouds and local storage into one view. Mail that a desktop client downloaded and removed from the server leaves only a local copy, and a local copy does not migrate. Contacts and calendar entries kept on a handset, in a local address book, or in a desktop app that never synced are not visible either. The same applies to files: when someone can reach a personal Google Drive and a Google Workspace account from the same laptop, files left in the wrong one are not in the connected source until they are moved there.

VaultMe keys a connection to an immutable internal identifier wherever the provider exposes one, rather than to anything a person can edit — a display name, an email address, a login. Google and Microsoft both expose such identifiers for user accounts, and other resource types can have them too; a shared drive keeps its internal ID even after it is renamed. Renaming an account or changing its primary address partway through a project therefore does not break the connection to it. Where no immutable identifier exists, VaultMe falls back to the best the provider offers, usually the login or email address, and that identifier is only as stable as the login itself.

Getting each side into a state where it can be connected at all, and confirming that the content people expect really is in the cloud rather than on their machines, is preparation work: see "Getting the source ready" and "Getting the destination ready".

What happens if a connection drops?

A connection can be lost while a migration is running, and VaultMe treats that as a pause rather than a failure. With the channel gone there is nothing to read or write through, so VaultMe stops work on the affected account and waits. The migration is not cancelled and the work already done is not discarded; the run picks up again once the connection is restored.

The same requirement applies after the initial run has finished. A sync-up migration (delta migration) reads from the source and writes to the destination exactly as the initial run did, so it cannot start until both sides are connected again. On a long project this is worth watching, because the index that pairs migrated items has a limited life and a connection left broken for long enough can outlast it, as described in "How sync-up migration works".

Disconnections almost always originate on the provider side, from changes that have nothing to do with VaultMe. The common triggers are:

• Credential and secret changes — a password reset, a key rotation, or an explicit revocation of the token VaultMe holds.
• Multi-factor authentication changes — a new policy, or a change to the verification factors on the identity an account was connected with.
• Environment-level admin configuration changes — an adjustment in the provider's admin console that changes how connected accounts can be accessed.
• Other provider-side security, policy, or identity changes that invalidate the connection state that already exists.

Which of these actually ends a connection depends on the provider, the resource type, and the connection method, so treat the list as indicative rather than complete.

The practical consequence is that identity and security work should be scheduled around your migration rather than during it. A password reset campaign, a multi-factor rollout, or a tightening of admin policy in the middle of a run will pause it, and every affected account has to be connected again before it moves on. Where such a change cannot wait, plan the reconnection as part of it. The same holds between runs for as long as sync-up migrations are still expected: keeping both sides connected is what keeps that option open.

Losing a connection and ending one deliberately are the same mechanism seen from two sides. When migration support is no longer needed, revoking VaultMe's access — from the provider's own account, environment, or admin controls, or from inside VaultMe where that control exists — closes the channel immediately, and VaultMe can no longer read from or write to that account. Revoking access does not undo anything: copies already written to the destination stay where they are, and so does the migration report. How revocation works and what happens after it is covered in "How VaultMe protects migration data".