Overview

  • Account linking securely connects a user's Google Account to their account on your platform using the OAuth 2.0 protocol, allowing Google apps and services to access data and services you host with user consent.

  • Google Account Linking can be used for various purposes, including sharing user data with Google apps, enabling features like Google TV and Smart Home integration, creating custom Google Assistant experiences, and streamlining account creation during sign-up.

  • There are three primary OAuth-based flows for Google Account Linking: Web OAuth (redirects to your website), App Flip (switches to your mobile app), and Streamlined Linking (completes the process within the Google surface).

  • Implementing the Web OAuth flow is required as a fallback for all account linking integrations.

  • Google Account Linking utilizes standard OAuth 2.0 token types (authorization code, access token, and refresh token) for secure communication and data sharing between systems.

Choose your integration path

Select the path that best suits your needs:

Path Best for Learn more
Universal Commerce Protocol (UCP) Merchants and retailers. UCP Docs
Standard Account Linking Smart Home, TV, and YouTube. Docs

Account linking enables Google Account holders to quickly, seamlessly and safely connect to your services. You may choose to implement Google Account Linking to share a user's data from your platform with Google apps and services.

The secure OAuth 2.0 protocol lets you safely link a user's Google Account with their account on your platform, thereby granting Google applications and devices access to your services.

Users can link or unlink their accounts and optionally create a new account on your platform with Google Account Linking.

Use cases

Some of the reasons to implement Google Account Linking are:

  • Share a user's data from your platform with Google apps and services.

  • Integrate with Google Shopping and AI surfaces (Search, Gemini) using the Universal Commerce Protocol (UCP).

  • Play your video and movie content using Google TV.

  • Manage and control Google Smart Home connected devices using the Google Home app and Google Assistant, "Hey Google turn on the lights".

  • Create user customized Google Assistant experiences and functionality with Conversational Actions, "Hey Google, order my usual from Starbucks".

  • Enable users to earn rewards by viewing eligible live streams on YouTube after linking their Google Account to a rewards partner account.

  • Pre-populate new accounts during sign-up with consensually shared data from a Google Account profile.

Capabilities & Requirements

The following matrix defines the support and recommendations for each linking flow.

Linking Flow Standard Features UCP Features
App Flip Recommended Recommended
Streamlined linking Recommended Recommended
OAuth linking Required (Fallback) Required (Fallback)
OAuth 2.1 Recommended Recommended

Agentic Development (MCP & UCP)

Large Language Models (LLMs) and AI Agents require robust authentication to access user data. Google Account Linking supports these emerging paradigms:

  • Model Context Protocol (MCP): GAL acts as the security handshake. Agents use OAuth 2.1 tokens to securely query your MCP server tools.

  • Universal Commerce Protocol (UCP): Enables shopping agents to access user profiles and payment vectors securely.

  • Improve user privacy by defining custom scopes to share only necessary data, increase user trust by clearly defining how their data is used.

  • Access to data and services hosted on your platform can be revoked by unlinking accounts. Implementing an optional token revocation endpoint lets you stay in sync with Google initiated events, while Cross-Account Protection (RISC) lets you notify Google of any unlinking events that take place on your platform.

Account linking flows

There are 3 Google Account Linking flows all of which are OAuth based and require you to manage or control OAuth 2.0 compliant authorization and token exchange endpoints.

During the linking process, you issue access tokens to Google for individual Google Accounts after obtaining account holders consent to link their accounts and share data.

OAuth linking

This is the OAuth linking flow that sends users to your website for linking. The user is redirected to your website to sign in to their account. Once signed in, the user consents to sharing their data, on your service, with Google. At that point, the user's Google Account and your service, are linked.

OAuth linking supports the authorization code and implicit OAuth flows. Your service must host an OAuth 2.0 compliant authorization endpoint for the implicit flow, and must expose both an authorization and token exchange endpoint when using the authorization code flow.

Figure 1. Account Linking on a user's phone with OAuth linking

OAuth-based App Flip Linking ('App Flip')

An OAuth flow that sends users to your app for linking.

OAuth-based App Flip Linking guides users as they move between your verified Android or iOS mobile apps and Google's platform to review the proposed data access changes and grant their consent to link their account on your platform with their Google Account. To enable App Flip your service must support OAuth linking or OAuth-based Sign in with Google Linking using the authorization code flow.

App Flip is supported for both Android and iOS.

How it works:

Google app checks if your app is installed on the user's device:

  • If the app is found, the user is "flipped" to your app. Your app gathers consent from the user to link the account with Google, and then "flips back" to the Google surface.
  • If app is not found or an error occurs during the app flip linking process, the user is redirected to Streamlined or OAuth linking flow.

Figure 2. Account Linking on a user's phone with App Flip

OAuth-based Streamlined Linking ('Streamlined')

OAuth-based Sign in with Google Streamlined linking adds Sign in with Google on top of OAuth linking, enabling users to complete the linking process without leaving the Google surface, thereby reducing frictions and drop-offs. OAuth-based Streamlined Linking offers the best user experience with seamless sign-in, account creation and account linking by combining Sign in with Google with OAuth linking. Your service must support OAuth 2.0 compliant authorization and token exchange endpoints. Additionally, your token exchange endpoint must support JSON Web Token (JWT) assertions and implement the check, create, and get, intents.

How it works:

Google asserts the user account and passes this information to you:

  • If an account exists for the user in your database, the user successfully links their Google Account with their account on your service.
  • If no account exists for the user in your database, the user can either create a new 3P account with the asserted information Google provides: email, name, and profile picture, or choose to sign in and link with another email (this will require them to sign-in to your service using OAuth linking).

Figure 3. Account Linking on a user's phone with Streamlined Linking

Which flow should you use?

We recommend implementing all flows to ensure users get the best linking experience. The Streamlined and App flip flows reduce linking friction as users are able to complete the linking process in very few steps. The OAuth linking flow has the lowest level of effort and is a good place to start after which you can add on the other linking flows.

Work with tokens

Google Account Linking relies on standard OAuth 2.0 token mechanisms. You issue access tokens and refresh tokens to Google after the user consents to link their account.

  • Access Tokens: Short-lived tokens used by Google to access your APIs.
  • Refresh Tokens: Long-lived tokens used by Google to obtain new access tokens when they expire.

For detailed protocol contracts and parameter requirements, see the Token Exchange Endpoint.

Persistent Linking

Persistent Linking is a core requirement for stable integrations. It ensures that user accounts remain linked even during transient network failures or periodic credential refreshes.

To implement persistent linking, use a "sliding window" approach: extend the expiration of the existing Refresh Token instead of rotating it (referencing RFC 6749 Section 6). This prevents race conditions and unintended unlinking that can occur if a new Refresh Token is issued but not successfully received or stored by Google.

Register with Google

We'll need details of your OAuth 2.0 setup and to share credentials to enable account linking. See registration for details.