OAuth-based App Flip Linking (App Flip) allows your users to quickly
link their accounts in your authentication system to their Google Accounts.
If your app is installed on your user's phone when they initiate the account
linking process, they are seamlessly flipped to your app to obtain user
authorization.

This approach provides a faster linking process since the user does
not have to re-enter their username and password to authenticate; instead,
App Flip leverages the credentials from the user's account on your app. Once a
user has linked their Google Account with your app, they can take advantage of
any integrations that you have developed.

You can set up App Flip for both iOS and Android apps.
![This figure shows the steps for a user to link their Google account
to your authentication system. The first screenshot shows how a user
can select your app if their Google account is linked to your app.
The second screenshot shows the confirmation for linking their
Google account with your app. The third screenshot shows a
successfully linked user account in the Google app.](https://developers.google.com/static/identity/images/app-flip-flow.png) **Figure 1.** Account linking on a user's phone with App Flip.

## Requirements

To implement App Flip, you must fulfill the following requirements:

- You must have an Android or iOS app.
- You must own, manage and maintain an OAuth 2.0 server which supports the OAuth 2.0 authorization code flow.

> [!NOTE]
> **Note:** Confirm that your OAuth2 implementation or provider supports the authorization code flow along with App Flip redirect URLs and client_ids as described in our guides.

### OAuth-based App Flip Flow

The following sequence diagram details the interaction between the User,
Google App, Your App, and Your Authorization Server for App Flip.
User Google App Your App Google Server Your Auth Server 1. Initiates linking 2. Deep link to Your App 3. Show Consent Screen 4. User Grants Consent 5. Get Auth Code 6. authorization_code 7. Return to Google App 8. Pass code to Google Server 9. Token Exchange (POST) 10. access_token, refresh_token 11. Store user tokens 12. Access user resources **Figure 2.** The sequence of events in the App Flip flow. If an authorization code is provided, the token exchange happens server-to-server, the same way it does in the browser-based OAuth linking flow.

### Roles and responsibilities

The following table defines the roles and responsibilities of the actors in the
App Flip flow.

| Actor / Component | GAL Role | Responsibilities |
|---|---|---|
| **Google App / Server** | OAuth Client | Initiates the linking process, triggers a deep link to your mobile app, exchanges the authorization code for tokens, and securely stores them to access your service's APIs. |
| **Your App** | Authorization Agent | Authenticates the user (typically using existing app credentials), obtains consent, and retrieves an authorization code from your server. |
| **Your Authorization Server** | Authorization Server | Validates authorization codes and refresh tokens, and issues access tokens to the Google Server. |

## Design guidelines

This section describes the design requirements and recommendations for the App
Flip account linking consent screen. After Google calls your app, your app
displays the consent screen to the user.

### Requirements

1. You must communicate that the user's account is being linked to Google, **not** to a specific Google product, such as Google Home or Google Assistant.

### Recommendations

We recommend that you do the following:

1. **Display Google's Privacy Policy.** Include a link to
   [Google's Privacy Policy](http://policies.google.com)
   on the consent screen.

2. **Data to be shared.** Use clear and concise language to tell the user what
   data of theirs Google requires and why.

3. **Clear call-to-action.** State a clear call-to-action on your consent
   screen, such as "Agree and link." This is because users need to
   understand what data they're required to share with Google to link their
   accounts.

4. **Ability to deny or cancel.** Provide a way for users to go back, deny, or
   cancel, if they choose not to link.

5. **Ability to unlink.** Offer a mechanism for users to unlink, such as a
   URL to their account settings on your platform. Alternatively, you can
   include a link to [Google Account](https://myaccount.google.com) where users
   can manage their linked account.

6. **Ability to change user account.** Suggest a method for users to switch
   their account(s). This is especially beneficial if users tend to have
   multiple accounts.

   - If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with *OAuth linking* and the *implicit* flow.
7. **Include your logo.** Display your company logo on the consent screen.
   Use your style guidelines to place your logo. If you wish
   to also display Google's logo, see
   [Logos and trademarks](https://www.google.com/permissions/logos-trademarks/).

![This figure shows an example consent screen with call-outs to the
individual requirements and recommendations to be followed when
you design a user consent screen.](https://developers.google.com/static/identity/images/app-flip-guidance.png) **Figure 2.** Account linking consent screen design guidelines.

## Implement App Flip in your apps

To implement App Flip, you need to modify the user authorization code in your
app to accept a deep link from Google.

To support App Flip on your Android app, follow the instructions on the
[Android implementation guide](https://developers.google.com/identity/account-linking/app-flip-android).

To support App Flip on your iOS app, follow the instructions on the
[iOS implementation guide](https://developers.google.com/identity/account-linking/app-flip-ios).

## Test App Flip

App Flip may be simulated using sample and test apps before verified production
apps and a working OAuth 2.0 server are available.

During App Flip a Google app will first open your app which then requests an
authorization code response from your OAuth 2.0 server, in the final step the
response is returned to the Google app.

### Prerequisites

To simulate a Google app and trigger the intent which launches your app,
download and install the App Flip Test Tool for
[Android](https://github.com/googlesamples/identity-appflip-tester-android)
and
[iOS](https://github.com/googlesamples/identity-appflip-tester-ios).

Download and install the App Flip Sample for
[Android](https://github.com/googlesamples/identity-appflip-android)
and [iOS](https://github.com/googlesamples/identity-appflip-ios)
to simulate your app and select an OAuth 2.0 response type.

### Test sequence

1. Open the App Flip Test Tool.
2. Press `Try Flip!` to launch your App Flip Sample app.
3. Select a response from the radio buttons in the Sample app.
4. Press `Send` to return a simulated OAuth 2.0 response back to the Test Tool.
5. Check the Test Tool log messages for an auth_code or error details.

### Production testing

App Flip may be tested in production after completing
[registration](https://developers.google.com/identity/account-linking/registration) and your OAuth 2.0 server
implementation.

A single Google Account and a
[task specific email address](https://support.google.com/a/users/answer/9308648)
are recommended for automated testing.

Accounts linking state can be viewed using
[Linked accounts](https://myaccount.google.com/accountlinking) when signed in as
the Google Account holder. Accounts may be unlinked between repeated tests from
here as well.

Optionally, you may choose to implement
[RISC](https://developers.google.com/identity/account-linking/unlinking#cross-account_protection_risc) to
programmatically unlink and notify Google of the change.