Security

Your product can use the Nest API to help prevent home intrusions.

When all family members are away from home, the structure enters away mode. When a Nest Cam detects a person, the Camera API's /last_event/has_person field changes to true.

These two states work together to trigger the Works with Nest Security API, as follows:

If a Nest Cam detects the presence of a person while the structure is in away mode, the structure enters deter mode.

When your product detects that the structure is in deter mode, your product can make the home "pretend" to be occupied by altering the home environment in some way, such as turning on the lights, playing music, or opening blinds to make an intruder more visible.

In this way, the home becomes a less inviting target for attack.

Requirements

To use the Security API:

  • Your client must have these permissions:
    Enable Home/Away Assist
    • Security state read / v1
    • Structure read/write / v1
    • Camera read / v3
  • The structure away state must be accurate, meaning:
    • All home occupants must be added as family members in the Nest app.
    • All family members must have the Nest app installed on their phone with Home/Away Assist enabled.
  • The structure must have at least one Nest Cam capable of sending person alerts. For some Nest Cam models, the Nest Cam must have a Nest Aware subscription to get person alerts.

Learn more about the alerts users get from different Camera models.

Security features

The security state escalates to deter when the following criteria are met:

  • Structure state is away.
  • Structure contains at least one Nest Cam that:
    • is online and actively streaming
    • triggers a last event where has_person = "true"

A deter state is re-evaluated after several minutes and relaxed to ok if no further has_person events have occurred.

The security state automatically switches to ok when the structure state is Home.

A Works with Nest product that reacts to a deter state should also react to the de-escalation of that state. For example, lights and music that turn on to simulate occupancy in a deter state, should eventually turn off after the www_security_state de-escalates to ok.

Security permissions

To use the security API, choose the Security state read / v1 permission.

There are no write permissions available for the security API.

Security values

Use the wwn_security_state field to view the security state.

Value Description
ok Normal operation, all is well in the structure
deter Person detected while the structure state is away

Test your integration

To test the Security API, you must have:

Setup

  1. In your Nest developer account, create or modify a client with the following permissions:
    • Security state read / v1
    • Structure read/write / v1
    • Camera read / v3
  2. In your home.nest.com account, delete any physical devices. This is necessary because the Nest Home Simulator only works with virtual devices.
  3. Authorize a Works with Nest connection.
  4. Read your structure's security state with this endpoint:
    https://developer-api.nest.com/structures/structure_id/wwn_security_state
    This request returns the string ok.

Change the security state to deter

  1. Log in to the Nest Home Simulator with your home.nest.com credentials.
  2. In Nest Home Simulator, set the Structure away status to away mode.
    Set structure to away
  3. Add a Camera to your structure.
    Add Camera
  4. Generate a person event. In the Camera settings, select Person and click Generate Event.
    Generate a person event
  5. After a few seconds, click End Current Event.
  6. Query your structure again to see the change to wwn_security_state. The security state is now deter. The security field de-escalates to ok after the has_person event times out (about one minute) or after you set the Structure away status to home.