Authorization

Developers can use the 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.

For a walkthrough of the authorization process, see the Authorize an Account page of the Device Access Quick Start guide.

For help with troubleshooting authorization errors, see Authorization Errors.

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 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 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 when accessing PCM, 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.

Unverified apps

The SDM API uses a restricted scope, which means that any apps that use this scope during authorization will be "unverified" unless OAuth API Verification is completed. When using Device Access for personal use, OAuth API Verification is not required.

You may see a "Google hasn't verified this app" screen during the authorization process, which appears if the sdm.service scope is not configured on your OAuth consent screen in Google Cloud. This screen can be bypassed by clicking the Advanced option and then clicking Go to Project Name (unsafe).

See Unverified app screen for more information.

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.

Revoke account authorization

There are multiple ways to deauthorize a Google account. The preferred method is for the user to use Partner Connections Manager (PCM) to modify account permissions. See Modify account permissions for more information. An access token can also be revoked by the following methods:

The user can revoke at https://myaccount.google.com/permissions.
The developer can pass the access token to the endpoint https://oauth2.googleapis.com/revoke. To learn more about Google OAuth and token revocation, see Revoking a token.

Embedded webviews

A new secure browser policy prohibits Google OAuth requests in embedded browser libraries commonly referred to as embedded webviews. All embedded webviews will be blocked. Embedded webview libraries are problematic because they allow a nefarious developer to intercept and alter communications between Google and its users. Embedded webviews not only affect account security, they could affect usability of your application.

If you're impacted by this policy, reference the Upcoming security changes to Google's OAuth 2.0 authorization endpoint in embedded webviews support article.