How to Choose Permissions and Write Descriptions

Permissions are key to your integration. They control the kind of data your product can access and whether it is authorized to read or write Nest device data. When you create a client, we'll ask you to choose permissions. Explore the API Reference to see how the data structure and permissions work together.

Choose permissions thoughtfully. You can change permissions later, but your users will be notified and asked to accept a permissions update.

Permissions version

When we introduce new permissions to the data model, we increment the client version number. To take advantage of these new features, you should update your client with new permissions for the data you want to access.

Permissions are designed around the types of data access each product might need.

Available permissions

This list describes the access available when you're using the latest permission version. See the API reference for detailed permission information and field availability.

Thermostat read

  • Grants read permission to most of the Thermostat data values
  • Grants read permission to most of the Structure data values

Thermostat read/write

  • Grants read permission to all of the Thermostat data values
  • Grants write permission to some of the Thermostat data values
  • Grants read permission to most of the Structure data values

Smoke + CO read

  • Grants read permission to all the Smoke+CO alarm data values
  • Grants read permission to most of the Structure data values

Away read

  • Grants read permission to most of the Structure data values

Away read/write

  • Grants read permission to most of the Structure data values
  • Grants read/write permission for away

ETA write

  • Grants read permission to most of the Structure data values
  • Grants write permission to eta

ETA read

  • Grants read permission to the eta begin timestamp

Structure read/write

  • Grants read/write permission to the structure name

Postal code read

Camera read

Camera read/write

Camera read + images

  • Grants read permission to all Camera data values

Camera read/write + images

  • Grants read permission to all Camera data values
  • Grants write permission to the is_streaming field

Energy read

Security State read

Example use cases and permissions

The permissions you choose should match the features of your product. Remember that we'll ask your users to agree that your product can access their shared data. Don't ask for more data than your product needs.

Thermostat example

If you're building a product that listens to temperatures and the Away state of the home, choose the Thermostat read permission.

Conversely, for a product that needs to actively modify target temperature, heat/cool mode, or fan timer, choose Thermostat read/write permission.

Protect example

If your product tracks smoke and CO state, choose the Smoke + CO alarm read permission.

Nest Cam example

You might have a product that uses motion events to turn on a lighting scene. In this case, choose Camera read permission.

A different product might use a connected pet activity sensor to send a notification when the dog is active, along with a gif of the dog's activity. For this case, choose Camera read + images permission.

Energy example

When your users are enrolled in the Rush Hour Rewards program, their Nest products change settings to save energy.

With the Energy read permission selected, your products can know if a user is subscribed to a Rush Hour Rewards program and when the peak periods begin and end.

ETA and Away example

If your product is focused solely on the home, and takes action when the user arrives or after the user leaves, choose Away read/write and ETA write permissions.

How to choose permissions

Choose the permissions that make sense for your product. For products that only check in and get status updates, choose a "read" permission. If your product is designed to set device values or status, choose a "read/write" permission.

Ultimately, you want your users to accept and authorize your product. To help users with this decision, you should only choose the permissions that match your product's features. If you choose all the permissions and your product's feature set doesn't match, it can cause users to question whether you can be trusted with their data.

For more information on changing permissions after you create a client, see Manage Client Version.

How to write permission descriptions

User authorization
Permission descriptions are user-facing, and appear in the Works with Nest user authorization page and the permissions view in the Nest app.

Permission descriptions should explain how your product benefits users.

When you write the description, include the client name, what it does for users, and the triggering event.

Use this template to write permission descriptions:

[Client name] [takes an action] [because/when...]

Example permission descriptions

  • FTL Magic Pathlights dim to save energy when your home is set to Away.
  • FTL Magic Pathlights illuminate to deter intruders when the Nest Cam Outdoor detects motion.

When you write your permission descriptions, be aware that:

  • The permission title cannot be changed
  • Permission descriptions must have a minimum of 5 words and contain 180 characters or less

For more information, see the User Experience Guidelines.