> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Auth Linking

> Attach multiple authentication methods to a single OMS Wallet for recovery and flexibility, with security guarantees against silent cross-provider linking.

An OMS Wallet can be associated with more than one authentication method. Whether a user authenticates
with Google, Apple, or email OTP, any linked method resolves to the same wallet address. The user is
always the same person regardless of which method they used to sign in.

This capability is separate from external wallet attestation. It concerns only the authentication
methods that grant access to a WaaS wallet, not EOA associations or external address verification.
Adding or removing a linked method does not produce a new wallet address and does not require any
on-chain transaction. The number of linked methods a wallet has does not affect its address or its
assets.

## What this unlocks

**Recovery** is the primary value. If a user loses access to one authentication provider, such as a locked
Google account or an inaccessible email address, they can recover the same wallet through any other linked
method. No assets are lost and no migration is required.

**Flexibility** is the secondary value. A user who onboards with one method can add another later without
producing a separate wallet. Both methods will always resolve to the same address.

## PrincipalID model

Wallet ownership is keyed to a stable internal identity called the Principal, not to any specific
authentication provider. When a user first authenticates, a PrincipalID is created and a wallet is
assigned to it. All subsequent authentication methods that are linked to that Principal resolve to the
same wallet.

The relationship looks like this:

* Many authentication methods can map to a single PrincipalID.
* A PrincipalID is associated with a wallet.
* Any login via a linked method reaches the same wallet address.

Changing or revoking a single authentication method does not change the PrincipalID or the wallet
address. The first method that creates the Principal establishes the wallet; subsequent methods are
additions to an existing account, not the creation of a new one. The wallet remains stable across
the full lifecycle of the authentication configuration.

When a user adds a second method, the system verifies that the new method is not already associated
with a different Principal. If it is, the link is rejected. This constraint preserves the one-to-one
relationship between an authentication credential and a single account.

## Security stance

* Linking always requires fresh authentication via the new method. The user must actively complete an
  authentication ceremony for the method being added. There is no silent cross-provider linking.
* Email matches across providers are surfaced as a hint in the UI only. If a verified email on Google
  matches a verified email on Apple, the system may suggest linking those accounts. That suggestion is
  never applied automatically.
* This design prevents email-only account takeover. Without this constraint, a compromised email provider
  could otherwise be used to silently claim another wallet through a shared email address.

## References

* [Authentication](/wallets/authentication): supported authentication methods and how they work.
* [OMS Wallet Infrastructure](/wallets/infrastructure): enclave-bound authentication model.