Design Overview

There are many decisions to make when you design and develop a Works with Nest product—decisions that affect how your product acts, looks, and feels. Decisions like:

  • What type of connection and service access to use
  • How to manage access tokens
  • The aesthetic design of your product

Works with Nest connection types

Your Works with Nest connection can be either Cloud-to-Cloud or App-to-Cloud. If you set up a server to manage API calls, then you have a Cloud-to-Cloud connection. If you make calls to the Nest API directly from your device, you have an App-to-Cloud connection.

Access Tokens

We recommend using a Cloud-to-Cloud connection, in conjunction with REST or REST Streaming.

Firebase SDKs should be used for an App-to-Cloud connection, but note that the supported versions have been deprecated.

For more info, see the Architecture Overview.

Real-time updates

When your users make a change (from either the Nest app or a Nest device), your Works with Nest product should update that information in real time by default. Use REST Streaming to provide your users with a real-time response.

For example, let's say your user adds a new device to their Nest account from the Nest app, and you want to reflect that in your product. If you use REST to retrieve the updated state of their Nest account through a set polling interval, your product may appear to lag, potentially resulting in a poor user experience.

Access tokens

An access token represents a user who has authorized your product to access Nest data. In some Works with Nest connections, you'll make API calls for a user with a single access token. In others, you'll use a different access token for each device the user has authorized.

Where to store access tokens

In an App-to-Cloud connection, each user's device is assigned a unique access token. Store each access token on the corresponding device.

In a Cloud-to-Cloud connection, each user is assigned a single access token, even when the user accesses your Works with Nest product on multiple devices. Store this access token on your server app.

Access token expiration

Because an access token is effectively non-expiring, you only need to get it once. Store the access tokens and use them in subsequent API calls.

Deauthorization and user quota

Use the deauthorization API when your users want to remove a Works with Nest connection. Instead of sending users to the Nest app, end the session from within your app.

When you make a deauthorization call, or if a user deauthorizes your product from the Nest app (removes a Works with Nest connection), we'll close any open network connections (sessions) and remove your Works with Nest connection from the Nest app. Subsequent API calls with that access_token fail.

If a user has multiple authorizations (App-to-Cloud), the user must remove all Works with Nest connections from all devices before we can remove that user from your quota.

Error codes on deauthorization

When your user removes a Works with Nest connection from your app or the Nest app, your product receives either a 401 Unauthorized error or an auth_revoked event, and open network connections will close. Your product should handle these conditions gracefully and notify the user.

Refresh/sync and access tokens

When you refresh or sync your product with new information, don't send the user through another authorization flow. Just refresh the product with new information.

Continuing to do this over time creates a large number of valid access tokens, creating a potential security risk, if your ability to secure these access tokens is compromised.

Works with Nest product aesthetics

Use these design guides when crafting the look and feel of your Works with Nest product:

  • User interface guide - use Nest assets in your Works with Nest product to complement our design philosophy
  • User experience guides - learn how to design an exceptional user experience for customers connecting your product to Nest
  • Nest icons - use Nest trademarks and the Nest brand, logos, and assets in your product packaging, websites, communications, advertising, and social media

Send feedback about...

Nest Developers
Nest Developers