Guía de inicio rápido de OAuth

Antes de comenzar

Antes de comenzar a usar OAuth con HubSpot, necesitarás:

*Debes ser un Súper administrador para instalar una aplicación en una cuenta de HubSpot


Cómo funciona

HubSpot soporta el tipo de otorgamiento del Código de autorización de OAuth 2.0, que puede dividirse en cuatro pasos:

  1. Tu aplicación abre una ventana del navegador para enviar al usuario al servidor HubSpot OAuth 2.0
  2. El usuario revisa los permisos solicitados y otorga acceso a la aplicación
  3. El usuario es redirigido a la aplicación con un código de autorización en la cadena de consulta
  4. La aplicación envía una solicitud al servidor de OAuth 2.0 para intercambiar el código de autorización por un token de acceso
 

En esta guía

Nota: Todos los ejemplos de código de esta guía están escritos en JavaScript (Node.js)

 

Aplicación de inicio rápido

Si es la primera vez que usas la autenticación OAuth con las API de HubSpot, te recomendamos que consultes la Aplicación de inicio rápido de OAuth 2.0, escrita en Node.js. Esta app de muestra está diseñada para que puedas comenzar a usar OAuth 2.0 lo más rápido posible mediante la demostración de todos los pasos que se detallan a continuación en Obtener tokens de OAuth 2.0

Obtener tokens de OAuth 2.0

Paso 1: Crea la URL de autorización y dirige al usuario al servidor OAuth 2.0 de HubSpot

Al enviar un usuario al servidor OAuth 2.0 de HubSpot, el primer paso es crear la URL de autorización. Esto identificará tu aplicación y definirá los recursos (los alcances) a los que solicita acceso en nombre del usuario. Los parámetros de consulta que puedes pasar como parte de una URL de autorización se muestran a continuación. Para obtener información más detallada sobre este paso, lee el documento de referencia.

Parámetros de consulta de la URL de autorización
Parámetro ¿Requerido? Descripción Ejemplo
client_id El ID del cliente identifica tu aplicación. Encuéntralo en la página de configuración de tu aplicación.

7fff1e36-2d40-4ae1-bbb1-5266d59564fb

scope Los alcances que tu aplicación solicita, separados por espacios codificados de URL.

contacts%20social

redirect_uri La URL a la que el usuario será redirigido después de autorizar a tu aplicación para los alcances solicitados. Para las aplicaciones de producción, se requiere https.

https://www.example.com/auth-callback

optional_scope No Los alcances que son opcionales para tu aplicación y se eliminarán si el portal de HubSpot seleccionado no tiene acceso a esos productos

automation

Una vez que hayas creado tu URL, envía al usuario a OAuth 2.0 para iniciar el proceso.

Ejemplos

Usando una redirección del lado del servidor:

// Build the auth URL const authUrl = 'https://app.hubspot.com/oauth/authorize' + `?client_id=${encodeURIComponent(CLIENT_ID)}` + `&scope=${encodeURIComponent(SCOPES)}` + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}`; // Redirect the user return res.redirect(authUrl);

Usando un enlace HTML:

<a href="https://app.hubspot.com/oauth/authorize?scope=contacts%20social&redirect_uri=https://www.example.com/auth-callback&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx">Install</a>

Paso 2: HubSpot solicita al usuario su consentimiento

HubSpot muestra una ventana de consentimiento al usuario que muestra el nombre de tu aplicación y una breve descripción de los servicios de la API de HubSpot a los que solicita permiso para acceder. El usuario puede otorgar acceso a tu aplicación.

oauth_2_grant_prompt

Nota: El usuario que instala la aplicación debe tener acceso a todos los alcances solicitados. Si no tienen el acceso requerido, la instalación fallará y serán dirigidos a una página de error. Si un usuario ve esta página de error de permisos, necesitará que un Súper administrador instale la aplicación.

Tu aplicación no hace nada en esta etapa. Una vez que se otorga el acceso, el servidor de HubSpot OAuth 2.0 enviará una solicitud a la URI de devolución de llamada definida en la URL de autorización.

Paso 3: Manejar la respuesta del servidor OAuth 2.0

Cuando el usuario haya completado la solicitud de consentimiento del paso 2, el servidor de OAuth 2.0 envía una solicitud GET al URI de redireccionamiento especificado en tu URL de autentificación. Si no hay problemas y el usuario aprueba la solicitud de acceso, la solicitud al URI de redireccionamiento se devolverá con un parámetro de consulta de code adjunto. Si el usuario no otorga acceso, no se enviará ninguna solicitud.

Ejemplo:
app.get('/oauth-callback', async (req, res) => { if (req.query.code) { // Handle the received code } });

Paso 4: Código de autorización de intercambio para tokens

Después de que tu aplicación reciba un código de autorización del servidor Oauth 2.0, puede intercambiar ese código por un token de acceso y actualización al enviar una solicitud POST codificada URL-form a  https://api.hubapi.com/oauth/v1/token con los valores que se muestran a continuación. Para obtener información más detallada sobre este paso, dedica un minuto a leer este documento de referencia.

Parámetro Descripción Ejemplo
grant_type Debe ser authorization_code authorization_code
client_id ID de cliente de tu aplicación 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret El secreto del cliente de tu aplicación 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri El URI de redireccionamiento desde el momento en que el usuario autorizó tu aplicación https://www.example.com/auth-callback
code El código de autorización recibido del servidor OAuth 2.0 5771f587-2fe7-40e8-8784-042fb4bc2c31
Ejemplo:
const formData = { grant_type: 'authorization_code', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, code: req.query.code }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

El cuerpo de la respuesta del token serán datos JSON con la forma:

{"refresh_token":"6f18f21e-a743-4509-b7fd-1a5e632fffa1","access_token":"CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I","expires_in":21600}

Nota: El token de acceso vencerá después de la cantidad de segundos indicada en el campo expires_in de la respuesta (seis horas). Para obtener información sobre cómo obtener un nuevo token de acceso, consulta Tokens de actualización de OAuth 2.0.

Uso de tokens de OAuth 2.0

Una vez que se complete el flujo de código de autorización, tu aplicación está autorizada para realizar solicitudes en nombre del usuario. Para ello, proporciona el token como token de portador en el encabezado HTTP Authorization. Los detalles específicos se pueden encontrar en el documento de referencia.

Ejemplo:
request.get('https://api.hubapi.com/contacts/v1/lists/all/contacts/all?count=1', { headers: { 'Authorization': `Bearer ${ACCESS_TOKEN}`, 'Content-Type': 'application/json' } }, (err, data) => { // Handle the API response } );

Actualización de tokens de OAuth 2.0

Los tokens de acceso de OAuth vencen periódicamente. Esto es para asegurarse de que, si se ven comprometidos, los atacantes solo tendrán acceso por un corto tiempo. La vida útil del token (seis horas por opción predeterminada) se especifica en el campo expires_in cuando se intercambia un código de autorización para un token de acceso.

Tu aplicación puede intercambiar el token de actualización recibido por un nuevo token de acceso enviando una solicitud codificada POST de formulario de URL a https://api.hubapi.com/oauth/v1/token con los siguientes valores. Para obtener información más detallada sobre este paso, consulta el documento de referencia.

Parámetro Descripción Ejemplo
grant_type Debe ser refresh_token refresh_token
client_id ID de cliente de tu aplicación 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
client_secret La clave del cliente de tu aplicación 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d
redirect_uri El URI de redireccionamiento desde el momento en que el usuario autorizó tu aplicación https://www.example.com/auth-callback
refresh_token El token de actualización recibido cuando el usuario autorizó a tu aplicación b9443019-30fe-4df1-a67e-3d75cbd0f726
Ejemplo:
const formData = { grant_type: 'refresh_token', client_id: CLIENT_ID, client_secret: CLIENT_SECRET, redirect_uri: REDIRECT_URI, refresh_token: REFRESH_TOKEN }; request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => { // Handle the returned tokens }

El cuerpo de la respuesta del token serán datos JSON con la forma:

// Sample response { "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1", "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I", "expires_in": 21600 }

El nuevo token de acceso puede usarse para hacer llamadas en nombre del usuario. Cuando el nuevo token venza, puedes seguir los mismos pasos nuevamente para recuperar uno nuevo.