Authorize an Account

With your Google Cloud Platform (GCP) and Device Access projects created, you can authorize a Google account with a supported Google Nest device for the Smart Device Management (SDM) API.

To view structures and devices, you must link a Google account to your Device Access project using the Partner Connections Manager (PCM). PCM allows the user to grant permission to allow developers to access their structures and device data.

In this guide, you serve as both the user and the developer.

  1. Open the following link in a web browser, replacing project-id with your Device Access Project ID and oauth2-client-id with the OAuth2 Client ID from your GCP Credentials:
    https://nestservices.google.com/partnerconnections/project-id/auth?
    redirect_uri=https://www.google.com&
    access_type=offline&
    prompt=consent&
    client_id=oauth2-client-id&
    response_type=code&
    scope=https://www.googleapis.com/auth/sdm.service
  2. If you have signed into Google with multiple accounts recently, you may be presented with an initial Choose an account screen with a list of your Google accounts. If so, select the Google account tied to the device(s) you wish to authorize for Device Access.
  3. On the Google Nest permissions screen you can grant structure and device permissions. Toggle on the permissions for your home (Step 1) and any devices in that home that are supported by the SDM API (Step 2), then click Done.
  4. On the Choose an account to continue to Project Name screen, where Project Name is the name of your GCP project, select the Google account you wish to authorize for the SDM API. Use the same Google account as before.
  5. On the Project Name wants to access your Google Account screen, click Allow to give the project permission to access your Google account.
  6. You should be redirected to https://www.google.com. The Authorization Code is returned as the code parameter in the URL, which should be in this format:
    https://www.google.com?code=authorization_code&
    scope=https://www.googleapis.com/auth/sdm.service
  7. Copy the authorization code.

Get an access token

Use the authorization code to retrieve an access token, that you can use to call the SDM API.

  1. Open a terminal and run the following curl command, replacing oauth2-client-id and oauth2-client-secret with the OAuth2 Client ID and Client Secret from your GCP Credentials, and authorization-code with the code you receive in the previous step:
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?
    client_id=oauth2-client-id&
    client_secret=oauth2-client-secret&
    code=authorization-code&
    grant_type=authorization_code&
    redirect_uri=https://www.google.com'
  2. Google OAuth returns two tokens, an access token and a refresh token:
    {
      "access_token": "access-token",
      "expires_in": 3599,
      "refresh_token": "refresh-token",
      "scope": "https://www.googleapis.com/auth/sdm.service",
      "token_type": "Bearer"
    }
    Copy both these values. The access token is used to call the SDM API and the refresh token is used to get a new access token.

Make a device list call

Authorization is not complete until you make your first devices.list call with your new access token. This initial call finishes the authorization process and enables events if you've already set up a Pub/Sub subscription.

Use curl to make this call for the devices endpoint:

curl -X GET 'https://smartdevicemanagement.googleapis.com/v1/enterprises/project-id/devices' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer access-token'

A successful call returns a list of devices linked to your Device Access project. Each device has its own unique list of available traits:

{
  "devices": [
    {
      "name": "enterprises/project-id/devices/device-id",
      "type": "sdm.devices.types.device-type",
      "assignee": "enterprises/project-id/structures/structure-id/rooms/room-id",
      "traits": { ... },
      "parentRelations": [
        {
          "parent": "enterprises/project-id/structures/structure-id/rooms/room-id",
          "displayName": "device-room-name"
        }
      ]
    }
  ]
}

How to use a refresh token

Access tokens for the SDM API are only valid for 1 hour, as noted in the expires_in parameter returned by Google OAuth. If your access token expires, use the refresh token to get a new one.

The command is similar to the access token one, except that you use a different grant_type.

  1. Open a terminal and run the following curl command, replacing oauth2-client-id and oauth2-client-secret with the OAuth2 Client ID and Client Secret from your GCP Credentials, and refresh-token with the code you received when initially getting the access token:
    curl -L -X POST 'https://www.googleapis.com/oauth2/v4/token?
    client_id=oauth2-client-id&
    client_secret=oauth2-client-secret&
    refresh_token=refresh-token&
    grant_type=refresh_token'
  2. Google OAuth returns a new access token:
    {
      "access_token": "access-token",
      "expires_in": 3599,
      "scope": "https://www.googleapis.com/auth/sdm.service",
      "token_type": "Bearer"
    }

Troubleshooting

To learn more about Google OAuth, see Using OAuth 2.0 to Access Google APIs.

Account linking error

For help with any errors encountered during account linking, see Partner Connections Manager (PCM) Error Reference.

Redirect uri mismatch

When going through authorization, you might run into a "Redirect uri mismatch" error. Make sure the redirect_uri value you're using in authorization calls is the same as the one you set for the OAuth 2.0 Client, as found in your GCP Credentials page.

Modify account permissions

To modify the permissions granted to a Device Access project, or disconnect it entirely, go to PCM:

https://nestservices.google.com/partnerconnections

This page displays all third-party developer services (Device Access projects) connected to your account. Select the Device Access project you wish to change. Use the next screen to modify permissions as desired.

To revoke only specific permissions for an authorized service, toggle the permissions you want to revoke and click the back arrow to save.

To disconnect an authorized service entirely, click Disconnect to revoke all permissions and access tokens the project has been granted for the account.

If PCM does not show the desired service, you may need to make a device list call first.