Última modificação: 22 de agosto de 2025
Use a API de tokens OAuth para gerar e gerenciar os tokens necessários para autorizar seu aplicativo público e as solicitações que ele faz. Por exemplo, você precisará usar essa API para buscar os tokens de acesso inicial e atualização durante o processo de instalação do aplicativo. Você o usará para continuar gerando novos tokens quando os antigos expirarem. Saiba mais sobre como trabalhar com OAuth. Antes de usar esses pontos de extremidade, você terá que criar um aplicativo público. Um usuário precisará então instalá-lo em sua conta para iniciar o acesso por OAuth.

​
Iniciar acesso de OAuth

Depois de criar seu aplicativo, um usuário pode instalá-lo em sua conta HubSpot usando o URL de instalação localizado nas configurações do seu aplicativo, que incluirá o client_id, redirect_uri e scopes como parâmetros de consulta. Você também pode incluir optional_scopes e state, se necessário. Depois que um usuário autorizar seu aplicativo e instalá-lo em sua conta, o URL de redirecionamento será anexado com um valor code, que você poderá usar para gerar um token de acesso e um token de atualização. O token de acesso será usado para autenticar solicitações feitas pelo seu aplicativo, enquanto o token de atualização será usado para obter um novo token de acesso quando o atual expirar. Saiba mais sobre como iniciar o OAuth para seu aplicativo.

​
Gerar acesso inicial e atualizar tokens

Para obter acesso OAuth e os tokens de atualização, faça uma solicitação POST codificada em formato de URL para /oauth/v1/token. No corpo da solicitação, você especificará vários parâmetros de autenticação, como client_id e client_secret, juntamente com o code repassado pelo URL de redirecionamento. Depois que um usuário autorizar seu aplicativo, o URL de redirecionamento será anexado a um valor code. Usando esse código, você gerará o token de acesso inicial e o token de atualização. Os tokens de acesso são de curta duração e você pode verificar o parâmetro expires_in ao gerar um token de acesso para determinar seu tempo de vida (em segundos). Por exemplo, sua solicitação pode ser semelhante a esta: 
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âmetroTipoDescrição
grant_typeStringDeve ser authorization_code para que a solicitação gere acesso inicial e atualize tokens.
codeStringO code retornado no URL de redirecionamento depois que o usuário instala o aplicativo.
redirect_uriStringO URL de redirecionamento definido no aplicativo.
client_idStringA ID do cliente do aplicativo.
client_secretStringO segredo do cliente do aplicativo.
Na resposta, você receberá o token de acesso junto com o token de atualização, que pode ser usado para atualizar o token de acesso. O campo expires_in especifica quanto tempo o token de acesso durará (em segundos). 
{
  "token_type": "bearer",
  "refresh_token": "1e8fbfb1-8e96-4826-8b8d-c8af73715",
  "access_token": "CIrToaiiMhIHAAEAQAAAARiO1ooBIOP0sgEokuLtAEaOaTFnToZ3VjUbtl46MAAAAEAAAAAgAAAAAAAAAAAACAAAAAAAOABAAAAAAAAAAAAAAAQAkIUVrptEzQ4hQHP89Eoahkq-p7dVIAWgBgAA",
  "expires_in": 1800
}

​
Atualizar um token de acesso

Usando um token de atualização, você pode gerar um novo token de acesso fazendo uma solicitação POST codificada em formato de URL para /oauth/v1/token. No corpo da solicitação, você especificará grant_type, client_id, client_secret e 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âmetroTipoDescrição
grant_typeStringDeve ser refresh_token para que a solicitação gere novos tokens de acesso a partir do token de atualização.
refresh_tokenStringO valor do token de atualização.
client_idStringA ID do cliente do aplicativo.
client_secretStringO segredo do cliente do aplicativo.

​
Recuperar metadados do token de acesso

Para obter informações sobre um token de acesso OAuth, incluindo o usuário para o qual o token foi criado e seu Hub ID correspondente, faça uma solicitação GET para /oauth/v1/access-tokens/{token}. Você receberá uma resposta contendo informações sobre o token de acesso do usuário e sua conta 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"
}

​
Observação:

Espera-se que os tokens de acesso da HubSpot flutuem em tamanho ao longo do tempo, à medida que atualizações forem feitas nas informações codificadas do token. É recomendável permitir que os tokens tenham até 512 caracteres para compensar quaisquer alterações.

​
Exclui um token de atualização.

Se um usuário desinstalar seu aplicativo, você poderá excluir o token de atualização fazendo uma solicitação DELETE para /oauth/v1/refresh-tokens/{token}. Isso excluirá apenas o token de atualização. Os tokens de acesso gerados com o token de atualização não serão afetados. Além disso, isso não desinstalará o aplicativo nas contas da HubSpot nem inibirá a sincronização de dados entre o aplicativo e a conta.