Última modificación: 22 de agosto de 2025
Usa la API de tokens OAuth para generar y gestionar los tokens necesarios para autorizar tu aplicación pública y las solicitudes que realiza. Por ejemplo, deberás usar esta API para obtener los tokens de acceso inicial y de actualización durante el proceso de instalación de la aplicación. Luego la usarás para seguir generando nuevos tokens cuando caduquen los antiguos. Más información sobre cómo trabajar con OAuth. Para poder usar estos endpoints, deberás crear una aplicación pública. Un usuario deberá instalarlo en su cuenta para iniciar el acceso con OAuth.

​
Iniciar el acceso con OAuth

Después de crear tu aplicación, un usuario puede instalarla en su cuenta de HubSpot usando la URL de instalación ubicada en la configuración de la aplicación, la cual incluirá client_id, redirect_uri y scopes como parámetros de consulta. También puedes incluir optional_scopes y state, si es necesario. Después de que un usuario autorice tu aplicación y la instale en su cuenta, la URL de redireccionamiento se adjuntará con un valor code, el cual puedes usar para generar un token de acceso y un token de actualización. El token de acceso se usará para autenticar las solicitudes que realice tu aplicación, mientras que el token de actualización se utilizará para obtener un nuevo token de acceso cuando caduque el actual. Más información sobre cómo iniciar OAuth para tu aplicación.

​
Generar tokens de acceso inicial y de actualización

Para obtener acceso OAuth y actualizar tokens, realiza una solicitud codificada POST de formulario URL a /oauth/v1/token. En el cuerpo de la solicitud, especificarás varios parámetros de autenticación, como client_id y client_secret, junto con el code devuelto a través de la URL de redireccionamiento. Después de que un usuario autorice tu aplicación, la URL de redireccionamiento se adjuntará con un valor code. Al usar este código, generarás el token de acceso inicial y el token de actualización. Los tokens de acceso son de corta duración y puedes consultar el parámetro expires_in al generar un token de acceso para determinar su duración (en segundos). Por ejemplo, el cuerpo de tu solicitud puede tener un aspecto similar al siguiente: 
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=authorization_code&code=bcf33c57-dd7a-c7eb-4179-9241-e01bd&redirect_uri=https://www.domain.com/redirect&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
ParámetroTipoDescripción
grant_typeCadenaDebe ser authorization_code para que la solicitud genere tokens de acceso inicial y de actualización.
codeCadenaEl code que se devuelve en la URL de redireccionamiento después de que el usuario instala la aplicación.
redirect_uriCadenaLa URL de redireccionamiento establecida de la aplicación.
client_idCadenaEl ID de cliente de la aplicación.
client_secretCadenaEl secreto del cliente de la aplicación.
En la respuesta, recibirás el token de acceso junto con el token de actualización, el cual puedes usar para actualizar el token de acceso. El campo expires_in especifica cuánto durará el token de acceso (en segundos). 
{
  "token_type": "bearer",
  "refresh_token": "1e8fbfb1-8e96-4826-8b8d-c8af73715",
  "access_token": "CIrToaiiMhIHAAEAQAAAARiO1ooBIOP0sgEokuLtAEaOaTFnToZ3VjUbtl46MAAAAEAAAAAgAAAAAAAAAAAACAAAAAAAOABAAAAAAAAAAAAAAAQAkIUVrptEzQ4hQHP89Eoahkq-p7dVIAWgBgAA",
  "expires_in": 1800
}

​
Actualizar un token de acceso

Al usar un token de actualización, puedes generar un nuevo token de acceso realizando una solicitud POST codificada de formulario URL a /oauth/v1/token. En el cuerpo de la solicitud, especificarás grant_type, client_id, client_secret y refresh_token. 
curl --request POST \
  --url https://api.hubapi.com/oauth/v1/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token&refresh_token=1e8fbfb1-8e96-4826-8b8d-c8af73715&client_id=7933b042-0952-4e7d-a327dab-3dc&client_secret=7a572d8a-69bf-44c6-9a34-416aad3ad5'
ParámetroTipoDescripción
grant_typeCadenaDebe ser refresh_token para que la solicitud genere nuevos tokens de acceso a partir del token de actualización.
refresh_tokenCadenaEl valor del token de actualización.
client_idCadenaEl ID de cliente de la aplicación.
client_secretCadenaEl secreto del cliente de la aplicación.

​
Recuperar metadatos del token de acceso

Para obtener información acerca de un token de acceso de OAuth, incluido el usuario para el que se creó el token y su Hub ID correspondiente, realiza una solicitud GET a /oauth/v1/access-tokens/{token}. Recibirás una respuesta con información sobre el token de acceso del usuario y su cuenta de HubSpot. 
{
  "token": "CNaKSIHAAEAQAAAARiO1ooBIOP0sgEokuLtATIU5m7Kzmjj0ihJJuKFq1TcIiHCqwE6MAAAAEEAAAAAAAAAAgAIUfmerBenQwc07ZHXy6atYNNW8XCVKA25hMVIAWgBgAA",
  "user": "user@domain.com",
  "hub_domain": "meowmix.com",
  "scopes": [
    "oauth",
    "crm.objects.contacts.read",
    "crm.objects.contacts.write"
  ],
  "signed_access_token": {
    "expiresAt": 1727190403926,
    "scopes": "AAEAAAAQ==",
    "hubId": 1234567,
    "userId": 293199,
    "appId": 111111,
    "signature": "5m7ihJJuKFq1TcIiHCqwE=",
    "scopeToScopeGroupPks": "AAAAQAAAAAAAAAACAAAAAAAAAAAAAIAAAAAAA4AEAAAAAAAAAAAAAABAC",
    "newSignature": "fme07ZHXy6atYNNW8XCU=",
    "hublet": "na1",
    "trialScopes": "",
    "trialScopeToScopeGroupPks": "",
    "isUserLevel": false
  },
  "hub_id": 1234567,
  "app_id": 111111,
  "expires_in": 1754,
  "user_id": 293199,
  "token_type": "access"
}

​
Nota:

Se espera que los tokens de acceso de HubSpot fluctúen en tamaño a lo largo del tiempo, ya que se harán actualizaciones en la información que está codificada en ellos. Es recomendable permitir tokens de hasta 512 caracteres para contemplar posibles cambios.

​
Eliminar un token de actualización

Si un usuario desinstala tu aplicación, puedes eliminar el token de actualización haciendo una solicitud DELETE a /oauth/v1/refresh-tokens/{token}. Esto solo eliminará el token de actualización. Los tokens de acceso generados con el token de actualización no serán eliminados. Además, esto no desinstalará la aplicación de las cuentas de HubSpot ni inhibirá la sincronización de datos entre la aplicación y la cuenta.