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](https://developers.google.com/nest/device-access/authorize) page of the Device Access Quick Start guide.

For help with troubleshooting authorization errors, see [Authorization
Errors](https://developers.google.com/nest/device-access/reference/errors/authorization).

## 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](https://developers.google.com/identity/protocols/OAuth2).

## 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](https://developers.google.com/nest/device-access/reference/errors/pcm).

### 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](https://developers.googleblog.com/2019/09/get-smart-about-preparing-your-app-for-OAuth-verfication.html) 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](https://console.developers.google.com/apis/credentials/consent/edit) 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](https://support.google.com/cloud/answer/7454865#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](https://developers.google.com/nest/device-access/authorize#modify_account_permissions)
for more information. An access token can also be revoked by the following
methods:

1. The user can revoke at
   <https://myaccount.google.com/permissions>.

2. 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](https://developers.google.com/identity/protocols/oauth2/native-app#tokenrevoke).

## 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](https://developers.googleblog.com/2021/06/upcoming-security-changes-to-googles-oauth-2.0-authorization-endpoint.html)
support article.