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.
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.
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:
Use these parameters in the URL:
||The URI to direct the user after successful authorization.|
||The OAuth 2.0 Client ID from your 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.|
||Value to use:
||Value to use:
||Value to use:
An authorization code is expected in return.
||Value to use:
The SDM API scope.
||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
code parameter in the redirect URI. Use this code to get an access
Add PCM to your app
In your app, add the PCM view using this URL:
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.
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 GCP. This screen can be
bypassed by clicking the Advanced option and then clicking Go to Project
See Unverified app screen for more information.
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.
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.