Referência de autorização

Solicitação de código de autorização

Dependendo do tipo de solicitação, implementamos diferentes comprimentos de código e valores de TTL (vida útil):

Fluxo TTL Tamanho do código
Web 10 minutos 16 caracteres
PIN 48 horas Oito caracteres

Parâmetros

Os parâmetros de autorização compatíveis com a API Nest são:

Nome Tipo Obrigatório Descrição
client_id string sim Disponível na página "Clientes OAuth".
redirect_uri string não Use-o para especificar o URI de redirecionamento desejado se vários URIs de redirecionamento estiverem configurados para seu cliente. Omita-o para usar seu URI de redirecionamento padrão.

Não inclua outros parâmetros no próprio parâmetro redirect_uri. Ele precisa corresponder exatamente a um URI de redirecionamento configurado para seu cliente.
state string sim Use essa opção para especificar um valor não detectável para combater ataques CSRF. Caso contrário, use o valor padrão STATE.

Mensagens de erro de autorização com base no PIN

As seguintes mensagens de erro podem ser exibidas para usuários durante solicitações de código de autorização com base no PIN:

Mensagem de erro do usuário Explicação
O ID do cliente ou os parâmetros de estado estão ausentes. O URL de autorização não tem o parâmetro client_id, state ou ambos. Verifique se o URL de autorização transmitido está completo e correto.
Ops! Encontramos um erro. Tente novamente. Esse erro ocorre nestes casos:
  • O serviço do Nest está desativado. Aguarde até que o serviço Nest seja restaurado.
  • Um cliente não existe para o client_id especificado. Verifique se o URL de autorização transmitido está usando o client_id correto.
A conexão com o Nome da empresa não está disponível no momento. Entre em contato com a Nest para mais informações. O cliente excedeu a cota do usuário. Envie seu cliente para revisão para adicionar mais usuários.

Redirecionar respostas de erro de autorização com base em URI

Para todas as respostas, content-type: application/json.

Parâmetros obrigatórios ausentes

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplicaçãoUm parâmetro obrigatório, PARAM_NAME, está ausente da solicitação do código de autorização.

redirect_uri não foi pré-registrado

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"input_data_error",
"error_description":"redirect_uri not pre-registered"
}
ExplicaçãoO parâmetro redirect_uri usado na solicitação de token de acesso não corresponde a nenhum dos URIs de redirecionamento configurados para o cliente.

Solicitação de token de acesso

Recomendamos que você obedeça a este padrão OAuth, que oferece maior segurança incluindo as credenciais do cliente no corpo da solicitação. As chamadas com credenciais de cliente no cabeçalho continuarão funcionando, mas não são recomendadas.

A solicitação de token de acesso está no formato de uma solicitação HTTP POST.

Parâmetros

Nome Tipo Obrigatório Descrição
code string sim É o código de autorização que é transmitido depois que o cliente concorda em conceder ao app acesso aos dados da Nest. Esse valor é fornecido por uma solicitação de código de autorização bem-sucedida.

Saiba como configurar a autorização
client_id string sim Disponível na página "Clientes OAuth".
client_secret string sim Disponível na página de clientes OAuth. Também pode ser chamada de chave de aplicativo.
grant_type string sim Precisa ser esta string: authorization_code

Resposta

Para todas as respostas, o tipo de conteúdo: application/json

Código de status HTTP Descrição Corpo
200 OK O token de acesso é retornado. Use o token de acesso nas chamadas para o serviço Nest. LONG é o número de segundos até o token expirar. {
"access_token":"STRING",
"expires_in":LONG
}

Ciclo de vida do token de acesso

Os tokens de atualização não são compatíveis, porque os tokens de acesso não expiram. Consulte a Visão geral da autorização para mais informações sobre o fluxo de autorização baseado na Web e em PIN.

Respostas de erro de token de acesso

Para todas as respostas, content-type: application/json.

Código de autorização expirado

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"oauth2_error",
"error_description":"authorization code expired"
}
ExplicaçãoO código de autorização expirou. Um novo código de autorização é necessário para solicitar um token de acesso.

Código de autorização não encontrado

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"oauth2_error",
"error_description":"authorization code not found"
}
ExplicaçãoO parâmetro code é inválido. Verifique se você está usando o código de autorização correto.

Cliente inativo

Detalhes
Código de status HTTP403 Proibido
Body{
"error":"client_not_active",
"error_description":"client is not active"
}
ExplicaçãoVerifique se você está usando os parâmetros corretos. Se os parâmetros estiverem corretos e o erro só ocorrer em alguns métodos de autorização, como a autorização com o Postman, mas não o Curl, talvez haja algo errado com sua sintaxe.

Esse erro também ocorre quando o cliente é desativado.

Chave secreta do cliente não encontrada

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"oauth2_error",
"error_description":"client secret not found"
}
ExplicaçãoO parâmetro client_secret é inválido. Verifique se você está usando o valor client_secret correto.

Parâmetros obrigatórios ausentes

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplicaçãoUm parâmetro obrigatório, PARAM_NAME, está ausente da solicitação de token de acesso.

redirect_uri não é permitido

Detalhes
Código de status HTTP400 Solicitação inválida
Body{
"error":"input_error",
"error_description":"redirect_uri not allowed"
}
ExplicaçãoO parâmetro redirect_uri foi usado na solicitação do token de acesso.