Referencia de autorización

Solicitud de código de autorización

Según el tipo de solicitud, implementamos diferentes longitudes de código y valores de TTL (tiempo de actividad):

Flujo TTL Longitud del código
Web 10 minutos 16 caracteres
PIN 48 horas 8 caracteres

Parámetros

Los parámetros de autorización compatibles con la API de Nest son los siguientes:

Nombre Tipo Obligatorio Descripción
client_id string Disponible en la página Clientes de OAuth.
redirect_uri string No Úsala para especificar el URI de redireccionamiento deseado si se configuraron varios URI de redireccionamiento para tu cliente. Omite este atributo para usar tu URI de redireccionamiento predeterminado.

No incluyas ningún otro parámetro dentro del parámetro redirect_uri, ya que debería coincidir exactamente con un URI de redireccionamiento configurado para tu cliente.
state string Úsalo para especificar un valor no adivinable a fin de combatir los ataques de CSRF. De lo contrario, usa el valor predeterminado de STATE.

Mensajes de error relacionados con la autorización basada en PIN

Los siguientes mensajes de error se pueden mostrar a los usuarios durante las solicitudes de código de autorización basadas en PIN:

Mensaje de error del usuario Explicación
Faltan los ID de cliente o los parámetros de estado. A la URL de autorización le falta el parámetro client_id o state, o ambos. Asegúrate de que la URL de autorización aprobada esté completa y sea precisa.
¡Uy! Detectamos un error. Vuelve a intentarlo. Este error ocurre por lo siguiente:
  • El servicio de Nest no funciona. Espera hasta que se restablezca el servicio de Nest.
  • No existe un cliente para la client_id determinada. Asegúrate de que la URL de autorización pasada use el client_id correcto.
La conexión con Nombre de la empresa no está disponible en este momento. Comunícate con Nest para obtener más información. El cliente superó la cuota del usuario. Envía a tu cliente a revisión para agregar más usuarios.

Redireccionamiento de respuestas de errores de autorización basadas en URI

Para todas las respuestas, tipo de contenido: application/json.

Faltan parámetros obligatorios.

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplicaciónFalta un parámetro obligatorio en la solicitud de código de autorización. PARAM_NAME

redireccionamiento de URI no registrado previamente

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"input_data_error",
"error_description":"redirect_uri not pre-registered"
}
ExplicaciónEl parámetro redirect_uri que se usó en la solicitud de token de acceso no coincide con ninguno de los URI de redireccionamiento configurados para tu cliente.

Solicitud de token de acceso

Te recomendamos que cumplas con este estándar de OAuth, que ofrece una mayor seguridad mediante la inclusión de las credenciales de cliente en el cuerpo de la solicitud. Las llamadas con credenciales de cliente en el encabezado seguirán funcionando, pero no se recomiendan.

La solicitud de token de acceso tiene el formato de una solicitud HTTP POST.

Parámetros

Nombre Tipo Obligatorio Descripción
code string El código de autorización que se pasa después de que el cliente acepta otorgar a tu app acceso a los datos de Nest Una solicitud de código de autorización exitosa proporciona este valor.

Más información para configurar la autorización
client_id string Disponible en la página Clientes de OAuth.
client_secret string Disponible en la página de clientes de OAuth; también puede llamarse clave de la aplicación.
grant_type string Debe ser esta string: authorization_code

Respuesta

Para todas las respuestas, tipo de contenido: application/json

Código de estado HTTP Descripción Cuerpo
200 OK Se muestra el token de acceso. Usa el token de acceso en las llamadas al servicio de Nest. LONG es la cantidad de segundos que vence el token. {
"access_token":"STRING",
"expires_in":LONG
}

Duración del token de acceso

No admitimos los tokens de actualización, ya que los tokens de acceso efectivamente no vencen. Consulta la Descripción general de la autorización para obtener más información sobre el flujo de autorización basado en la Web y en PIN.

Respuestas de error del token de acceso

Para todas las respuestas, tipo de contenido: application/json.

Venció el código de autorización

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"authorization code expired"
}
ExplicaciónEl código de autorización venció. Se necesita un nuevo código de autorización para solicitar un token de acceso.

No se encontró el código de autorización

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"authorization code not found"
}
ExplicaciónEl parámetro code no es válido. Verifique que esté usando el código de autorización correcto.

El cliente no está activo

Detalles
Código de estado HTTP403 Forbidden
Body{
"error":"client_not_active",
"error_description":"client is not active"
}
ExplicaciónVerifica que estés usando los parámetros correctos. Si los parámetros son correctos y el error solo se produce en algunos métodos de autorización (por ejemplo, la autorización se realiza de forma correcta con Postman, pero no se usa Curl), es posible que haya un problema con la sintaxis.

También se produce este error si el cliente está desactivado.

No se encontró el secreto del cliente

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"client secret not found"
}
ExplicaciónEl parámetro client_secret no es válido. Verifica que estés usando el valor de client_secret correcto.

Faltan parámetros obligatorios.

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"oauth2_error",
"error_description":"missing required parameters: PARAM_NAME"
}
ExplicaciónFalta un parámetro obligatorio, PARAM_NAME, en la solicitud de token de acceso.

redireccionamiento de URI no permitido

Detalles
Código de estado HTTP400 Bad Request
Body{
"error":"input_error",
"error_description":"redirect_uri not allowed"
}
ExplicaciónSe usó el parámetro redirect_uri en la solicitud de token de acceso.