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 Code	400 Bad Request
Body	{ "error":"oauth2_error", "error_description":"missing required parameters: PARAM_NAME" }
Explanation	A required parameter, PARAM_NAME, is missing from the authorization code request.

redirect_uri not pre-registered

Details
HTTP Status Code	400 Bad Request
Body	{ "error":"input_data_error", "error_description":"redirect_uri not pre-registered" }
Explanation	The 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 Code	400 Bad Request
Body	{ "error":"oauth2_error", "error_description":"authorization code expired" }
Explanation	The authorization code is expired. A new authorization code is needed to request an access token.

Authorization code not found

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

Client not active

Details
HTTP Status Code	403 Forbidden
Body	{ "error":"client_not_active", "error_description":"client is not active" }
Explanation	Check 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 Code	400 Bad Request
Body	{ "error":"oauth2_error", "error_description":"client secret not found" }
Explanation	The client_secret parameter is invalid. Check that you are using the correct client_secret value.

Missing required parameters

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

redirect_uri not allowed

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