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 Request error. 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:

Claim Description
iss Issuer Claim: This is a URL which you host, and it's shared with Google during registration.
aud Audience Claim: This identifies Google as the JWT recipient. It must be set to google_account_linking.
jti JWT ID Claim: This is a unique ID that you generate for every security event token.
iat Issued At Claim: This is a NumericDate value that represents the time when this security event token was created.
toe Time of Event Claim: This is an optional NumericDate value that represents the time at which the token was revoked.
exp Expiration Time Claim: Do not include this field, as the event resulting in this notification has already taken place.
events Security Events Claim: This is a JSON object, and must include only a single token revocation event containing the following fields:

  • subject_type: This must be set to oauth_token.
  • token_type: This is the type of token being revoked, either access_token or refresh_token.
  • token_identifier_alg: This is the algorithm used to encode the token, and it must be hash_SHA512_double.
  • token: This is the ID of the revoked token.

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.

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