Authentication and Authorization with OAuth 2.0

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.

OAuth 2.0 flow
OAuth 2.0 flow

Configure your Works with Nest product

If you have not already done so, register and configure a product.

If you have an existing product, check the Overview tab on the Product page find its OAuth 2.0 credentials.

If you have not yet developed an actual product, but you want to walk through the authorization process, feel free to create a test configuration.

Redirect URI or PIN-based authorization?

Redirect URI or PIN

When you are configuring your product, you are prompted to enter a redirect URI or leave the redirect URI field 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 field blank.

If your product has a browser component, the best practice is to include a redirect URI. The redirect URI allows the PIN to be communicated transparently so that the user doesn't need to enter it manually. The redirect URI should point to a site on your server or in your cloud.

  • One common use case for a redirect URI is to bring up a page that has a structure picker, allowing the user to select a primary residence or a vacation home, for example.
  • Another example might be a deep link within your mobile app.
  • A third example is when the validation accepts localhost. In this case, the URI doesn't actually function as a redirect, but takes the authorization code and uses it to exchange for a token.

Request permissions

The product configuration includes a set of permissions (also called scopes). Scope is variable parameter that controls the set of resources and operations that an access token permits. During the access-token request, your product sends one or more values in the scope parameter. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front.

Result

When you save the configuration, your product is assigned a unique client ID and client secret (called "Product ID" and "Product Secret" on the Overview tab of the Products page). In addition, your product 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.

OAuth details

Request an authorization code

After your product 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 product 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:

Works with Nest

Go ahead and click [ACCEPT] yourself to see what the user sees. By clicking the [ACCEPT] button, the user is approving your products's request to access their data.

PIN experience

If you left the Redirect URI field blank in your product 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.

Pincode

Redirect URI experience

If you included a redirect URI in your product 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.

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.

Test for CSRF attacks

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.

CSRF attack
CSRF attack

To help prevent CSRF attacks, we recommend that you always submit a non­guessable state when requesting authorization.

This way, your client application can verify that the access codes obtained from the Nest cloud are in response to requests made by your client application, not some other client application. In effect, your client can authenticate itself.

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 to your client 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 client receives this state value and is 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 re­computable 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:

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, 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 access token request. All four parameters are required.

Parameter Description
client_id The "product ID" generated in Step 1
client_secret The "product secret" generated 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 access token request examples in various languages.

Postman example (auth)

Postman provides an easy way to test an access token request.

On the Headers tab, make sure Content-Type = application/x-www-form-urlencoded.

POST header to get access token

On the Body tab, include the following key:value pairs.

POST body to get access token

Access token response

A successful access token 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 access token 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.

GET to read data

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.

Send feedback about...

Nest Developers
Nest Developers