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.

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 structure 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.

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.

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 structure, 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.

Camera example

If your product 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 occupancy, and takes action when the user arrives or after the user leaves, choose Away read/write and ETA write permissions.

Available permissions

The following tables describe the access available when you're using the latest permission version. See the API reference for detailed permission information and field availability.

The different permission types are:

  • Read - View settings on the device.
  • Write - Change settings on the device.
  • Read/Write - Both view and change settings on the device.
  • Images Read (Camera only) - View your camera’s settings, show images or video when there is sound or motion, and share your video stream if it is public.
  • Images Read/Write (Camera only) - View and configure your camera’s settings, turn it on or off, show images or video when there is sound or motion, and share your video stream if it is public.

Thermostat

Permissions
Thermostat read Grants read permission to all Thermostat values
Thermostat read/write Grants read permission to all Thermostat values
Grants write permission to the following Thermostat values:
Grants read permission to all Structure data values
Energy read Grants read permission to Energy Rush Hour event start and end times

Camera

Permission
Camera read Grants read permission to all Camera data values except:
Camera read/write Grants the same read permission as Camera read
Grants write permission to is_streaming
Camera + Images read Grants read permission to all Camera data values
Camera + Images read/write Grants read permission to all Camera data values
Grants write permission to is_streaming

Smoke+CO Alarm

Permission
Smoke+CO Alarm read Grants read permission to all Smoke+CO alarm data values
Grants read permission to the following Structure data values:
  • Away state
  • Structure name, country code, and time zone
  • List of all devices in the structure

Security

Permission
Security State read Grants read permission to the Structure security state

Other Permissions

Permission
Away read Grants read permission to the following Structure data values:
  • Away state
  • Structure name, country code, and time zone
  • List of all devices in the structure
Away read/write Grants the same read permission as Away read
Grants write permission to Away state
ETA read Grants read permission to eta_begin
ETA write Grants write permission to eta
Grants read permission to the following Structure data values:
  • ETA
  • Away state
  • Structure name, country code, and time zone
  • List of all devices in the structure
Structure read/write Grants read/write permission to the Structure name
Postal code read Grants read permission to the Structure postal code