Última modificación: 8 de octubre de 2025
‘OAuth es un método seguro de autenticación para tu aplicación. Utiliza tokens de autorización en lugar de una contraseña para conectar tu aplicación a una cuenta de usuario. ’;
OAuth es un método seguro de autenticación que usa tokens de autorización en lugar de una contraseña para conectar tu aplicación a una cuenta de usuario. Iniciar el acceso de OAuth es el primer paso para permitir a los usuarios instalar tu aplicación en sus cuentas de HubSpot.
Recursos recomendados
- La guía de inicio de OAuth te ayudará a comenzar con una aplicación de ejemplo.
- Este tutorial de HubSpot Academy ofrece una introducción rápida en el uso de OAuth con HubSpot, incluyendo un desglose del flujo de HubSpot a OAuth y cómo actualizar un token de acceso.
Configurar la autenticación OAuth
Para configurar la autenticación OAuth para tu aplicación:
-
Usa el ID de cliente y el secreto del cliente, junto con los parámetros de consulta y los permisos que se describen a continuación, para crear la URL de autorización.
-
Envía a los usuarios que deseen instalar la aplicación la URL de autorización, donde tendrán una pantalla que les permitirá seleccionar su cuenta y acceder a la integración. Puedes establecer que la URL de autorización sea para una cuenta de HubSpot específica agregando el ID de cuenta entre
/oauth/ y /authorize, como se muestra a continuación. Después de permitir el acceso, se redireccionarán a tu aplicación mediante una redirect_url, que tendrá un parámetro adjunto de consulta de código. Usarás ese código y el secreto del cliente para obtener un access_token y refresh_token de HubSpot.
- Ejemplos de URL de autorización
- Cualquier cuenta:
https://app.hubspot.com/oauth/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
- Cuenta específica (ID 123456):
https://app.hubspot.com/oauth/123456/authorize?client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&scope=contacts%20automation&redirect_uri=https://www.example.com/
- Ejemplo de URL de redireccionamiento:
https://example.com/?code=xxxx
- Ejemplo de error:
https://www.example.com/?error=error_code&error_description=Human%20readable%20description%20of%20the%20error
-
Usa el
access_token para autenticar las llamadas a la API realizadas a esa cuenta de HubSpot.
-
Una vez que expire el
access_token, usa el refresh_token para generar un nuevo access_token.
Parámetros de consulta
Los siguientes parámetros de solicitud son obligatorios al crear una URL de autorización para tu aplicación:
| Parámetro | Descripción | Cómo se usa |
|---|
client_id | Un ID que sirve como identificador único para tu aplicación. | Obténlo desde la página de configuración de autorización o “Auth” de tu aplicación (como se ha descrito anteriormente). |
redirect_uri | La URL a la que serán redireccionados los visitantes al recibir acceso a la aplicación. | También designarás esto en la página de configuración de autenticación de tu aplicación. Nota: Por razones de seguridad, esta URL debe utilizar https en producción. (Si realizas la prueba con localhost, puedes utilizar http.) También debes usar un dominio, ya que las direcciones IP no son compatibles. |
scope | Un conjunto de permisos separados por espacios a los que tu aplicación necesita acceder. | Todos los permisos que hayas marcado en la configuración de Autenticación de la aplicación se tratarán como obligatorios, por lo que deberás incluirlos en este parámetro. De lo contrario, la página de autorización mostrará un error. Además, los usuarios recibirán un error si intentan instalar tu aplicación en una cuenta que no tiene acceso a un permiso incluido. Ve la documentación de referencia de permisos para conocer más detalles sobre los endpoints que pueden tener permisos específicos. |
Los siguientes parámetros son opcionales:
| Parámetro | Cómo usar | Descripción |
|---|
optional_scope | Un conjunto separado por espacios de permisos opcionales para tu aplicación. | Los permisos opcionales se eliminarán automáticamente de la solicitud de autorización si el usuario selecciona una cuenta de HubSpot que no tiene acceso a esa herramienta (por ejemplo, autorizar el acceso a Content Hub Enterprise en una cuenta gratuita de HubSpot). Si estás usando permisos opcionales, deberás verificar el token de acceso o el token de actualización para ver cuáles se otorgaron. Consulta la documentación de referencia sobre permisos para obtener más detalles. |
state | Si este parámetro está incluido en la URL de autorización, el valor se incluirá en un parámetro de consulta de estado cuando el usuario sea dirigido a redirect_uri. | Un valor de cadena que se puede usar para mantener el estado del usuario cuando se redirecciona de regreso a la aplicación. |
Configurar permisos
OAuth requiere que configures permisos o alcances, para tu aplicación. Cada permiso proporciona acceso a un conjunto de endpoints de la API de HubSpot y permite a los usuarios otorgar a la aplicación acceso a herramientas específicas en su cuenta de HubSpot.
El acceso a las API o endpoints específicos depende del nivel de la cuenta de HubSpot. Si tu aplicación puede funcionar con varios tipos de cuentas de HubSpot, puedes usar el parámetro optional_scope para incluir los permisos con los que trabajas. De esta manera, los clientes que usan las cuentas gratuitas de HubSpot aún pueden autorizar la aplicación, incluso si no pueden acceder a todos los permisos. La aplicación debe verificar y manejar cualquier permiso para el que no esté autorizada.
La lista completa de permisos está disponible aquí.
Documentos relacionados
Métodos de autenticación en HubSpot
Guía de inicio de OAuth
Gestión de tokens