The Nest API uses the OAuth 2.0 protocol for authentication and authorization.
Before your product can access private data using the Nest API, it must obtain an access token that grants access to that API. A single access token can grant varying degrees of access to multiple sections of the API.
The authorization sequence begins when your product redirects a browser to a Nest URL with query parameters indicating the requested access. Nest handles the user authentication, session selection, and user consent. The result is an authorization code, which your product can exchange for an access token. Your product can then use the access token to make calls to the Nest API.
Configure your Works with Nest client
To find the OAuth 2.0 credentials for your client, check the Overview tab of the client page.
Redirect URI or PIN-based authorization?
When you are configuring your client, you are prompted to enter a redirect URI or leave the redirect URI fields blank to use PIN-based authorization.
If your product is a device that doesn't have an associated app or web page (for example, a fitness tracker, an appliance, or a security panel), leave the Redirect URI fields blank.
If your product has a browser component, the best practice is to include a redirect URI.
Request permissions
The client configuration includes a set of permissions (also called scopes). A permission is a variable parameter that controls the set of resources and operations that an access token permits. It is generally a best practice to request permissions incrementally, at the time access is required, rather than up front.
Result
When you save the configuration, your client is assigned a unique Client ID and Client Secret. In addition, your client is assigned an authorization URL.
The authorization URL includes a state parameter that you can use to test for possible cross-site request forgery (CSRF) attacks. See Test for CSRF attacks.
Request an authorization code
After your client is configured, you can request an authorization code (sometimes called a PIN code). The authorization code is not the final token that you use to make calls to Nest. It is used in the next step of the OAuth 2.0 flow to exchange for an actual access token. This step provides assurance directly from Nest to the user that permission is being granted to the correct product, with the agreed-upon access.
The user experience
We present a Works with Nest page that asks the user to grant access to your product. This identifies your product and outlines the particular user permissions (scopes) that your product has requested. The words on the screen come from your client configuration.
To test this yourself, load the authorization URL from Step 1 into a browser. You should see a Works with Nest access request page:
Go ahead and click [ACCEPT] yourself to see what the user sees. By clicking the [ACCEPT] button, the user is approving your product's request to access their data.
PIN experience
If you leave the Redirect URI fields blank in your client configuration, the user is redirected to a Nest page that displays a PIN (authorization code). Your device UI should then prompt the user to enter the PIN manually.
Redirect URI experience
If you include a redirect URI in your client configuration, the user is redirected to a page in your cloud (or localhost), and Nest automatically sends the authorization code to the user's device.
Test for CSRF attacks
Before accepting the authorization code, your product should ensure that the value returned in the state parameter matches the state value from your original authorization request. This ensures that you are dealing with the actual user and not a malicious script. If the state values do not match, you should throw a 401 Unauthorized HTTP error code in response.
A CSRF attack is an attack that forces an end user to execute unwanted actions on a web application in which they're currently authenticated.
To help prevent CSRF attacks, we recommend that you always submit a
nonguessable state when requesting authorization.
This way, your Works with Nest integration can verify that the access codes obtained from the Nest cloud are in response to requests made by your product, not some other product.
Example:
Let’s say in your client config, you specify the redirect URI:
http://localhost:5000/callback
Let’s also say your client sends the 7tvPJiv8StrAqo9IQE9xsJaDso4 state in the
authorization URL:
https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
The user consents to the request.
The Nest cloud returns the state parameter as part of the redirect URI:
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
Your product receives this state value and should be programmed to only accept redirects with a verifiable state.
There are multiple ways to generate a non-guessable state parameter. You can provide randomized state values from a dictionary kept in memory or a recomputable value. You can use a private key with some easily verifiable variables—for example, the client ID and a session cookie—to compute a hashed value. This results in a byte value that is difficult to guess without the private key. Another suggestion is to hash the current date and time. With this approach, your application must save the time of transmission to verify it or allow a sliding period of validity (for example, using the Time-based One-Time Password algorithm [TOTP]).
After computing the keyed-hash message authentication code (HMAC), base-64 encode it and pass it to the Nest cloud as a state parameter.
Here’s a Python example that uses datetime:
import base64
import datetime
import hmac
import hashlib
def generate_state_parameter(client_id, private_key):
date = datetime.datetime.today()
raw_state = str(date) + client_id
hashed = hmac.new(private_key, raw_state, hashlib.sha1)
state = base64.b64encode(hashed.digest())
return (state, date)
Authorization code error messages
If the authorization code request fails, users see an error message. For more information on these messages and how to prevent them, see the Authorization Reference.
Exchange authorization code for an access token
The final step in obtaining an access token is for your product to ask for one using the authorization code it just acquired. This is done by making an "x-www-form-urlencoded" HTTP POST request.
Include the below parameters in the request. All four parameters are required.
| Parameter | Description |
|---|---|
| client_id | The Client ID in Step 1 |
| client_secret | The Client Secret in Step 1 |
| code | The authorization code received in Step 2 |
| grant_type | The value of this field should always be: authorization_code |
Before each POST call, get a new authorization code. To do this, reload your
authorization URL. Then change the POST's code parameter to include the new
authorization code.
Code examples (auth)
See examples in various languages.
Postman example (auth)
Postman provides an easy way to test OAuth requests.
On the Headers tab, make sure Content-Type =
application/x-www-form-urlencoded.
On the Body tab, include the following key:value pairs.
Access token response
A successful request returns a JSON object containing the following fields:
access_token— The access token for the user. This value must be kept secure.expires_in— The number of seconds remaining, from the time it was requested, before the token expires.
Access token error messages
If the request fails, you receive an error in the form of an HTTP Status Code. For more information on these errors and how to prevent them, see the Authorization Reference.
Make authenticated requests
After a product obtains an access token, it sends the token to a Nest API in an HTTP authorization header. It is possible to send tokens as URI query-string parameters, but we don't recommend it, because URI parameters can end up in log files that are not completely secure.
Access tokens are valid only for the set of operations and resources described in the scope of the token request. For example, if an access token is issued for the Nest Thermostat API, it does not grant access to the Nest Camera API.
Code examples (read/write)
Postman example (read/write)
Postman provides an easy way to test API calls using Content-Type =
application/json.
Invalid tokens
If you make an API call using an invalid token, you receive a 401 Unauthorized response back from the server. A token could be invalid and in need of regeneration because:
- It has expired
- The user has revoked the permission they initially granted to your product
It is important that you code your product to properly handle a 401 Unauthorized error by redirecting the user back to the start of the authorization workflow.
Works with Nest connection closed
If a user removes a Works with Nest
connection,
your product receives an auth_revoked event and the connection closes.