Implementing Account Linking

Implementing account linking with Google takes 3 simple steps.

Step 1. Configure your server

Accounts are linked with industry standard OAuth 2.0 flows. Actions on Google supports the implicit and authorization code flows.

In addition, we highly recommend you implement streamlined identity flows that offer a great experience for your users to sign-in to their existing accounts or even create new accounts. The experience takes two clicks from your users and doesn’t require any username, password, or long configuration steps. To enable the streamlined identity experience on your existing OAuth 2.0 server, see Streamlined Identity Flows.

Step 2: Enable Account Linking

You need to configure the account linking parameters using the Actions on Google console.

  1. Navigate to the Actions console.
  2. Select or create a new project.
  3. Go to Advanced Options > Account linking.

  4. Follow the step-by-step instructions to set up account linking:

  5. If your Action supports seamless account linking:

    1. Enable Add quick account linking under step 3 and fill out the fields.

    2. Under Testing Instructions, provide a sample username and password to help us test seamless account linking during the review process for your Actions project then hit save.

Once account linking is set up, you can enable your Action to trigger account linking in two ways: when your Action is invoked or while in conversation with your Action. The following sections describe how to do this.

Account linking at invocation time

To enable account linking at invocation, complete the following steps:

  1. Whitelist the following redirect URI:<google developer project ID>
  2. In your Dialogflow project, click Integrations in the left navigation.
  3. Click on the Google Assistant card (enable the card if it's not already enabled).
  4. Select Sign in Required for the welcome intent and any other intent that requires sign in.
  5. In the expanded OAuth 2.0 form, fill out the fields with your OAuth 2.0 client configuration. When filling in scopes, ensure they are space delimited.
  6. Preview and test the authorization flow:

    Test on a device:

    1. Open the Google app and go to the Discover tab.
    2. Click on the account linking card, which launches the account linking flow. The Google app and the device must be signed into the same account that you use to test the Action.

    Testing on the Actions simulator

    1. Invoke your Action. Since it's the first time invoking the Action with your Google account, the Assistant notifies you that you must link your account.
    2. In the Log area, copy and paste the URL from the debugInfo.sharedDebugInfo.debugInfo field into your web browser. You will be redirected to the authentication URL for your own server that was specified in Dialogflow or in the Actions Console.
    3. Follow the OAuth login flow to completion. The account linking works if you are redirected to with a URL param of result_code=SUCCESS.
    4. In the Actions simulator, invoke your Action again. Your Action responds to the user and receives an access_token in all HTTP requests to your fulfillment. Use the Node.js client library function Conversation.user.access.token to obtain the token.

During the conversation

You can have users sign-in to their accounts that are associated with your service by requesting the actions.intent.SIGN_IN intent during a conversation.

The Request the signin helper section of this doc shows how to request this intent; the Getting the results of the helper section of this doc shows how to check if the user successfully linked their account after the request.

Request the signin helper

Request this intent if you are unable to find an accessToken in the user object This means that the user has not yet linked their account.

app.intent('ask_for_sign_in', (conv) => {
  conv.ask(new SignIn());
  "conversationToken": "{\"state\":null,\"data\":{}}",
  "expectUserResponse": true,
  "expectedInputs": [
      "inputPrompt": {
        "initialPrompts": [
            "textToSpeech": "PLACEHOLDER_FOR_SIGN_IN"
        "noInputPrompts": []
      "possibleIntents": [
          "intent": "actions.intent.SIGN_IN",
          "inputValueData": {}

Getting the results of the helper

After the user responds to the helper, you receive a request to your fulfillment and can check to see if the user successfully linked their account.

After requesting the actions.intent.SIGN_IN intent, you will receive an argument containing a SignInStatus with a value of either OK, CANCELLED, or ERROR. If the status is OK you should be able to find an accessToken in the user object.

app.intent('ask_for_sign_in_confirmation', (conv, params, signin) => {
  if (signin.status !== 'OK') {
    return conv.ask('You need to sign in before using the app.');
  // const access = conv.user.access.token;
  // possibly do something with access token
  conv.ask('Great! Thanks for signing in.');
  "isInSandbox'": false,
  "surface": {
    "capabilities": [
        "name": "actions.capability.AUDIO_OUTPUT"
        "name": "actions.capability.SCREEN_OUTPUT"
  "inputs": [
      "rawInputs": [
          "query": "i think so",
          "inputType": "VOICE"
      "arguments": [
          "name": "SIGN_IN",
          'extension': {
            "@type": "",
            "status": "OK"
      "intent': "actions.intent.SIGN_IN"
  "user": {
    "userId": "user123"
  "device": {
    "locale": "en-US"
  "conversation": {
    "conversationId": "1494606917128",
    "type": "ACTIVE",
    "conversationToken": "[\"_actions_on_google_\"]"

Step 3: Verify your implementation

If you are only using standard account linking without seamless identity, you can validate your implementation by using the OAuth 2.0 Playground tool. In the tool, do the following steps:

  1. Click the gear icon to open the OAuth 2.0 Configuration window.
  2. In the OAuth Endpoints field, select Custom.
  3. Specify your OAuth 2.0 endpoints and the Google client ID and client secret in the corresponding fields.
  4. In the Step 1 section, don't select any Google scopes; instead, type a scope valid for your server, and click Authorize APIs.
  5. In the Step 2 and Step 3 sections, step through the OAuth 2.0 flow and verify that each step works as intended.

Seamless identity verification

If you are using seamless identity, validate the steps above, then use the gala-demo tool to validate the assertion flows and a physical device to test your Action.

In the demo tool, complete the following steps:

  1. Click the login button to grant permission to the tool to access your profile information (this is only needed the first time you use the tool).
  2. In the service ID field, provide your Google Cloud Project ID plus a _dev suffix. For example, if your project ID is my_gcp_project, enter my_gcp_project_dev.

  3. Add all scopes needed for testing in the next field and click on Start Demo.

  4. An account chooser screen will be displayed. You can either use your logged account (triggering the seamless identity flows) or click to use another account. In that case, your standard OAuth flow will be triggered by presenting the Authorization screen.

  5. At the end of the flow, the tool displays your access token. Use this token in subsequent calls to your Action, when you test your Action on a physical device.


If your account linking is failing for whatever reason, the logs in the Actions Console are a good place to start figuring out what's going wrong. You can learn more about troubleshooting in the Actions Console here.


See Actions on Google Policies for specific account linking policies. If users sign in to your service using Google Sign-In, you must comply with the API Terms of Service, including not requesting irrelevant permissions.