Authorization

Developers can use the Smart Device Management (SDM) API to view and manage Google Nest devices on behalf of users. The SDM API validates that the user manages the devices being accessed, that the user has consented to the developer reading or writing each device's traits, and that the developer has been whitelisted for access to each trait.

To use the SDM API for device management, the developer must first be authorized by the user.

See the Authorize page of the Device Access Quick Start guide for a walkthrough of the authorization process.

OAuth flow

The SDM API uses a three-legged Google OAuth flow for user authorization:

  • When a user wishes to authorize a developer for management of Nest devices, the developer sends the user to Partner Connections Manager (PCM), where the user logs into their Google account.
  • The user selects permissions to grant for the developer in PCM.
  • The user provides consent via OAuth, granting the developer an Authorization Code.
  • The developer uses the Authorization Code to retrieve an Access Token.
  • The developer uses the Access Token with calls to the SDM API for device management.

To learn more about Google OAuth and how to get set up, see Using OAuth 2.0 to Access Google APIs.

Partner Connections Manager (PCM)

PCM is provided by the SDM API. It is a view that lists all structures, devices, and access options that the user can grant to the developer. The user chooses what to give access to during the authorization process and retains control of that access.

The options selected in PCM map to trait groups, which are collections of traits the developer will be granted access to. Some trait groups are linked together, depending on what type of integration the developer is offering to the user, and the user must grant permissions for those linked trait groups to enable that integration. Otherwise, the user has the ability to grant permissions for individual, unlinked trait groups as desired.

Enable PCM

To enable the PCM view for a user, replace the standard Google API OAuth 2.0 endpoint with this new OAuth endpoint for the Authorization Request:

https://nestservices.google.com/partnerconnections/project-id/auth

Use these parameters in the URL:

Parameter Description
redirect_uri The URI to direct the user after successful authorization.
client_id The OAuth 2.0 Client ID from your Google Cloud Platform (GCP) Project. Make sure this is the same one associated with your Project ID. Note that an OAuth Client ID must be valid and unique to a project, and cannot be shared with other projects.
access_type Value to use: offline
prompt Value to use: consent
response_type Value to use: code
An authorization code is expected in return.
scope Value to use: https://www.googleapis.com/auth/sdm.service
The SDM API scope.
state Optional. An opaque value used by the developer client to maintain state between the request and callback.

Example PCM URL:

https://nestservices.google.com/partnerconnections/
  2f6989ca-c756-4625-8cdc-d5b1edfb2dcd/auth?
  redirect_uri=https://www.example.com/api/link/M258KP8OWYZDVQ&
  client_id=418235700063-sdkiav89orn5r1nvrcr5t210qqjimq8l.apps.googleusercontent.com&
  access_type=offline&
  prompt=consent&
  response_type=code&
  scope=https://www.googleapis.com/auth/sdm.service

After the user gives permission, an Authorization Code is returned as the code parameter in the redirect URI. Use this code to get an access token.

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

Add PCM to your app

In your app, add the PCM view using this URL:

https://nestservices.google.com/partnerconnections

When the user is logged in, this page shows all their linked Device Access developers, as well as a list of all structures and devices with toggles for granting and revoking permissions. The user can also disconnect a partner connection on a per-partner basis from this page.

Access tokens

All calls to the SDM API to manage authorized structures and devices must use the unique access token granted to the developer by the user during authorization. Access tokens are short-lived and must be refreshed regularly to ensure continued access.

If a user later revokes developer access to a structure or a device, the access token immediately expires and cannot be refreshed, and the developer will no longer be able to call the SDM API on behalf of that user.