Autenticación
Usar OAuth
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.
Última modificación: 28 de agosto de 2025
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.
Nota:
- Cualquier aplicación diseñada para ser instalada por varias cuentas de HubSpot o que se anuncie en el mercado de aplicaciones debe usar OAuth.
- Los usuarios que instalen aplicaciones en su cuenta de HubSpot deben ser superadministradores o tener permisos de acceso al mercado de aplicaciones.
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:- En primer lugar, crea una aplicación en una cuenta de desarrollador de HubSpot. Después de crear la aplicación, podrás encontrar el ID de cliente de la aplicación y el secreto del cliente en la página de autenticación de la configuración de 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 unaredirect_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/
- Cualquier cuenta:
- 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
- Ejemplos de URL de autorización
-
Usa el
access_tokenpara autenticar las llamadas a la API realizadas a esa cuenta de HubSpot. -
Una vez que expire el
access_token, usa elrefresh_tokenpara generar un nuevoaccess_token.
Nota:
- La aplicación no aparecerá como Aplicación conectada en la cuenta de un usuario a menos que generes el token de actualización y el token de acceso inicial.
- Los tokens de acceso reflejan los permisos solicitados desde la aplicación y no reflejan los permisos o limitaciones de lo que un usuario puede hacer en su cuenta de HubSpot. Por ejemplo, si un usuario tiene permisos para ver solo los contactos de su propiedad, pero autoriza una solicitud para el permiso
crm.objects.contacts.read, el token de acceso resultante puede ver todos los contactos de la cuenta y no solo los que son propiedad del usuario que autoriza.
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. |
| 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.
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í.