1.1: OAuth Account Linking
Introduction and Business Impact
To leverage the Google APIs, OAuth is required to grant your integration the necessary merchant access to onboard them onto Free Listings and Paid Ads.
Your application must use OAuth 2.0 to authorize requests. No other authorization protocols are supported.
UX Guidance
Goal: Have merchants authorized to share the use of their data for Google app.
Design principle: Ask for the right permission at the right time. If merchants don't give the permission, fail gracefully.
The merchant is prompted to provide access permissions. Find an example of how these instructions can be surfaced to the merchant:
Once the merchant goes through these initial steps, there are three possible outcomes:
Outcome #1: If the merchant agrees to all permissions:
If the merchant provides full permissions, they check all of the boxes and is prompted to continue the onboarding process.
Outcome #2: If the merchant doesn't agree to Ads
The merchant checks all of the boxes except the permission related to Google Ads. They continue the onboarding process and later, when they are creating a new Google Ads account or connecting to an existing account, they are prompted again to give permissions:
Outcome #3: If product data or site verification is unchecked, the merchant are blocked from continuing to onboard
All of the preceding options result in the same error message:
Tech Guidance
Choose the authorizing requests with OAuth 2.0
There are two methods to select a merchant authentication method:
| OAuth 2.0 for non-service accounts (Highly Recommended) | OAuth 2.0 for service accounts |
|---|---|
| An OAuth 2.0 client identifies the application and lets end users grant your application limited access to their Google data. It allows your application to access Google Cloud APIs on behalf of the end user. The listed occurrences result in the access token being invalidated which should be accounted for in the code: ● User has revoked access ● User has changed password ● Number of granted refresh tokens exceeded limit ● Refresh token has not been used within 6 months |
Service accounts are special Google accounts that can be used by applications to access Google APIs programmatically using OAuth 2.0.It uses an OAuth 2.0 flow that does not require human authorization. Instead, it uses a key file that only your application can access. Note: Applications using service accounts for authentication can only access their own Merchant Center account. If you are writing a third-party application that needs access to your clients' Merchant Center accounts, see the Authorizing Requests guide instead. Note: a Cloud project is required and allows the creation of up to 100 service accounts. See documentation |
Set up the OAuth flow
OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
Because your app accesses protected (non-public) data, you need an OAuth 2.0 client ID. Google APIs use OAuth 2.0 protocol for authentication and authorization. Google supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.
Learn More
Things to be aware about using OAuth for the content API for shopping:
Ensure you have set the access_type to offline: Access tokens periodically expire and become invalid credentials for a related API request.
Refresh an access token: You can do this without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes. associated with the token (learn more).
OAuth implementation in the Libraries: We highly recommend you use Google API Client Libraries.
Scope: You need to request your merchant to grant you read and write access to its Google Account with the Google Merchant Center OAuth scope: https://www.googleapis.com/auth/content.
You can use OAuth to get key user profile info.
Scopes to use for your integration
Depending on which type of integrations you are planning to build for your merchants, we recommend asking for all necessary scopes at this moment.
| Program | Scope | Which format is scope required |
|---|---|---|
| Content API | https://www.googleapis.com/auth/content |
Free Listings |
| Site Verification | https://www.googleapis.com/auth/siteverification |
Free Listing & Paid Ads |
| Ads | https://www.googleapis.com/auth/adwords |
Free Listing & Paid Ads |
Verify if merchants have granted OAuth access
Merchants have to tick boxes in the OAuth consent flow to grant you access to specific scopes: If the required scopes are missing, explain to merchants why these are required and request the permission again (more details). Not having access to all of these permissions prevent merchants from fully onboarding.
Call the following API endpoint to check the granted scopes:
https://www.oauth2.googleapis.com/token
The URL returns the following information:
- access_token
- scopes granted to the user
- time before token expiration
Sensitive Scopes and OAuth Verification Process
Some scopes used by OAuth APIs are considered sensitive and require a verification process. Additional information and examples can be found at OAuth for the content API.
Sensitive app scope to meet policy: Need to make sure that your app complies with Google's API Services User Data Policy. You also need to agree to the API terms of service.
Confirm your app doesn't fall under any of the use cases listed in the Exceptions to verification requirements.
Verify ownership of your project's authorized domains: using the Search Console. Use an account that is either a Project Owner or a Project Editor of your Cloud Console project.
Make sure all branding information on the OAuth consent screen matches and is valid such as: the project name shown to users, support email, homepage URL, and privacy policy URL, accurately represents the app's identity.
Request your app for sensitive scope with the verification process: Follow the process which requires filling out a form, providing justification and sending a video.