This reference page documents the Google-offered endpoints and interfaces that
your app uses during the [OAuth-based Account Linking](https://developers.google.com/identity/account-linking/oauth-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](https://tools.ietf.org/html/rfc6749).
- **JSON Web Tokens (JWT)** : Compliant with [RFC 7519](https://tools.ietf.org/html/rfc7519) (for Streamlined Linking and RISC).
- **Security Event Tokens** : Compliant with [RFC 8417](https://tools.ietf.org/html/rfc8417) (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_PARTNER_ID` path
parameter is the Google Account Linking Partner ID (or Project ID) configured
during [registration](https://developers.google.com/identity/account-linking/registration).

- **URL:** `https://oauth-redirect.googleusercontent.com/r/YOUR_PARTNER_ID`
- **Sandbox URL:** `https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PARTNER_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](https://tools.ietf.org/html/rfc6749#section-4.1.2.1) (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](https://developers.google.com/identity/account-linking/unlinking#cross-account_protection_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)](https://tools.ietf.org/html/rfc7519)

## App Flip "Flip-Back" Interface

For [App Flip](https://developers.google.com/identity/account-linking/app-flip-overview), 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](https://developers.google.com/identity/account-linking/app-flip-android).

- **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](https://developers.google.com/identity/account-linking/app-flip-ios).

- **Format:** `<return_url>?code=AUTHORIZATION_CODE&state=STATE_STRING`