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:

  

  • 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