Authorization Reference

Authorization code request

Depending on the request type, we implement different code lengths and TTL (Time-to-Live) values:

Flow TTL Code length
Web 10 minutes 16 characters
PIN 48 hours 8 characters

Parameters

The authorization parameters supported in the Nest API are:

Name Type Required Description
client_id string yes Available on the OAuth Clients page.
redirect_uri string no Use this to specify the desired redirect URI if multiple redirect URIs are configured for your client. Omit it to use your default redirect URI.

Do not include any other parameters within the redirect_uri parameter itself, it should match a redirect URI configured for your client exactly.
state string yes Use this to specify a non-guessable value to combat CSRF attacks. Otherwise, use the default value of STATE.

PIN-based authorization error messages

The following error messages can be displayed to users during PIN-based authorization code requests:

User Error Message Explanation
Missing client ID or state parameters. The authorization URL is missing either the client_id or state parameter, or both. Ensure the passed authorization URL is complete and accurate.
Oops! We've encountered an error. Please try again. This error occurs from the following:
  • The Nest service is down. Wait until the Nest service is restored.
  • A client doesn't exist for the given client_id. Ensure the passed authorization URL is using the correct client_id.
Connecting to Company Name is currently unavailable. Please contact Nest for more information. The client has exceeded the user quota. Submit your client for review to add more users.

Redirect URI-based authorization error responses

For all responses, content-type: application/json.

Missing required parameters

Details
HTTP Status Code400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplanationA required parameter, PARAM_NAME, is missing from the authorization code request.

redirect_uri not pre-registered

Details
HTTP Status Code400 Bad Request
Body{
"error":"input_data_error",
"error_description":"redirect_uri not pre-registered"
}
ExplanationThe redirect_uri parameter used in the access token request does not match any of the redirect URIs configured for your client.

Access token request

We recommend you comply with this OAuth standard, which offers increased security by including the client credentials in the request body. Calls with client credentials in the header will continue to work, but are not recommended.

The access token request is in the form of an HTTP POST request.

Parameters

Name Type Required Description
code string yes The authorization code that is passed after your customer agrees to give your app access to Nest data. This value is provided by a successful authorization code request.

Learn how to set up Authorization
client_id string yes Available on the OAuth Clients page.
client_secret string yes Available on the OAuth Clients page; may also be called application key.
grant_type string yes Must be this string: authorization_code

Response

For all responses, content-type: application/json

HTTP Status Code Description Body
200 OK Access token is returned. Use the access token in calls to the Nest service. LONG is the number of seconds until the token expires. {
"access_token":"STRING",
"expires_in":LONG
}

Access token lifetime

We don't support refresh tokens, because access tokens are effectively non-expiring. See the Authorization Overview for more information on web- and PIN-based authorization flow.

Access token error responses

For all responses, content-type: application/json.

Authorization code expired

Details
HTTP Status Code400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"authorization code expired"
}
ExplanationThe authorization code is expired. A new authorization code is needed to request an access token.

Authorization code not found

Details
HTTP Status Code400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"authorization code not found"
}
ExplanationThe code parameter is invalid. Check that you are using the correct authorization code.

Client not active

Details
HTTP Status Code403 Forbidden
Body{
"error":"client_not_active",
"error_description":"client is not active"
}
ExplanationCheck that you're using the correct parameters. If the parameters are correct, and the error only occurs for some authorization methods (for example, authorization is successful using Postman, but not using Curl), there might be something wrong with your syntax.

This error also occurs if your client is deactivated.

Client secret not found

Details
HTTP Status Code400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"client secret not found"
}
ExplanationThe client_secret parameter is invalid. Check that you are using the correct client_secret value.

Missing required parameters

Details
HTTP Status Code400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplanationA required parameter, PARAM_NAME, is missing from the access token request.

redirect_uri not allowed

Details
HTTP Status Code400 Bad Request
Body{
"error":"input_error",
"error_description":"redirect_uri not allowed"
}
ExplanationThe redirect_uri parameter was used in the access token request.

Code samples

See these code samples for more help on building your own authorization flow.