Google Account Linking API

This reference page documents the Google-offered endpoints and interfaces that your app uses during the OAuth-based Account Linking process.

Prerequisites and standards

To successfully interact with these Google endpoints, your integration must adhere to the following standards:

• OAuth 2.0: Compliant with RFC 6749 .
• JSON Web Tokens (JWT): Compliant with RFC 7519 (for Streamlined Linking and RISC).
• Security Event Tokens: Compliant with RFC 8417 (for RISC).
• HTTPS: All requests must be made over a secure HTTPS connection.

OAuth Redirect URI

The endpoint where your service redirects the user's browser after successful authentication and consent. The YOUR_PROJECT_ID path parameter is the ID you configure during registration .

• URL: https://oauth-redirect.googleusercontent.com/r/ YOUR_PROJECT_ID

• Sandbox URL: https://oauth-redirect-sandbox.googleusercontent.com/r/ YOUR_PROJECT_ID

• Method: GET (using browser redirect)

Request Parameters

When redirecting the user back to Google, parameters must be appended to the URL. Depending on the OAuth flow used, these parameters are formatted either as a query string (Auth Code flow) or as a URL fragment (Implicit flow).

Parameter	Description
code	(Required for Auth Code Flow) The authorization code generated by your service.
state	(Required) The unmodified state value originally received from Google.
access_token	(Required for Implicit Flow) The long-lived access token generated by your service.
token_type	(Required for Implicit Flow) Must be bearer .

Error Responses

If the request to the OAuth redirect URI is malformed, you will receive an HTTP 400 Bad Requesterror. The response body will contain a JSON object with the following structure:

Field	Description
sendPostBody	Determines if the JS should redirect to the redirectUri with POST. Typically false in this scenario.
errorMessage	An error message to be displayed to the client when the redirect cannot be completed. For missing fragments, this is "A URI fragment or query string must be set."

OAuth 2.0 Error Responses

If the user denies consent or your service encounters an error, your service must redirect the user back to the OAuth redirect URI with standard OAuth 2.0 error parameters (such as error=access_denied ). Google will process these parameters and display an appropriate error screen to the user.

RISC API (Optional)

Used by your service to proactively notify Google when a user unlinks their account on your platform using the RISC protocol, ensuring both platforms stay in sync.

• URL: https://risc.googleapis.com/v1/events:publish
• Method: POST
• Authentication:Requires a Google Service Account token with appropriate permissions.
• Content-Type: application/json

Security Event Token Claims

Security Event Tokens that you use to notify Google of token revocation events must conform to the requirements in the following table:

For more information on field types and formats, see JSON Web Token (JWT)

App Flip "Flip-Back" Interface

For App Flip , your mobile app must return the authorization code or access token to the Google app.

Android (Intent Result)

Your app is opened using an Intent. After consent, it finishes and returns a result to Google. For more information, see the Android implementation guide .

• Action: com.google.android.gms.auth.CODE_AVAILABLE
• Extras: code , state , access_token , token_type .

iOS (Custom URL Scheme and Universal Links)

Your app opens Google using either a custom URL scheme or an HTTPS Universal Link. For more information, see the iOS implementation guide .

• Format: <return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING