Última modificação: 8 de outubro de 2025
‘Aprenda como configurar o OAuth para seu aplicativo usando este guia de início rápido e o aplicativo Node.js de exemplo.’;
Antes de começar
Antes de começar a usar o OAuth com o HubSpot, você precisará ter:
Como ele funciona
O HubSpot oferece suporte ao tipo de concessão do Código de autorização do OAuth 2.0, que pode estar dividido em quatro etapas básicas:
- Seu aplicativo abre uma janela do navegador para enviar o usuário ao servidor HubSpot OAuth 2.0
- O usuário analisa as permissões solicitadas e concede acesso ao aplicativo
- O usuário é redirecionado de volta ao aplicativo com um código de autorização na sequência de consulta
- O aplicativo envia uma solicitação ao servidor OAuth 2.0 para trocar o código de autorização por um token de acesso
Neste guia
Ínício rápido do aplicativo
Se esta for a primeira vez que você usa a autenticação OAuth com as APIs da HubSpot, é altamente recomendável que você verifique o Aplicativo de início rápido OAuth 2.0, escrito em Node.js. Este aplicativo de exemplo foi projetado para ajudá-lo a começar a usar o OAuth 2.0 o mais rápido possível, demonstrando todas as etapas descritas abaixo na seção sobre como obter tokens OAuth abaixo.
Obtendo tokens OAuth
1. Crie o URL de autorização e direcione o usuário para o servidor OAuth 2.0 da HubSpot
Quando um usuário é direcionado para o servidor OAuth 2.0 da HubSpot, a primeira etapa consiste na criação do URL de autorização. Isso identificará seu aplicativo e definirá os recursos (escopos) cujo acesso ele está solicitando em nome do usuário. Os parâmetros de consulta que você pode passar como parte de um URL de autorização são mostrados na tabela abaixo. Para obter informações mais detalhadas sobre essa etapa, leia o documento de referência.
Campos marcados com * são obrigatórios.
| Parâmetro | Descrição | Exemplo |
|---|
client_id* | O ID do cliente identifica seu aplicativo. Encontre-o na página de configurações do seu aplicativo. | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
scope* | Os escopos que seu aplicativo está solicitando, separados por espaços codificados por URL (%20). | oauth%20crm.objects.contacts.read |
redirect_uri* | O URL para o qual o usuário será redirecionado depois que ele autorizar seu aplicativo para os escopos solicitados. Para aplicações de produção, https é necessário. | https://www.example.com/auth-callback |
optional_scope | Os escopos que são opcionais para o aplicativo e serão ignorados se o portal do HubSpot selecionado não tiver acesso a esses produtos | automation |
state | Um valor de sequência de caracteres exclusivo que pode ser usado para manter o estado do usuário quando ele é redirecionado de volta ao seu aplicativo. | WeHH_yy2irpl8UYAvv-my |
Depois de criar sua URL, inicie o processo de conexão do OAuth enviando o usuário para ela.
Os blocos de código abaixo fornecem exemplos de uso de diferentes tipos de redirecionamento:
Usando um redirecionamento do lado do 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)}` +
`&state=${encodeURIComponent(STATE)}`;
// Redirect the user
return res.redirect(authUrl);
<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&state=xxxxxxxx"
>Install</a
>
userA.integration.com e userB.integration.com). Para fazer isso, use o parâmetro state para codificar mais informações sobre o estado do usuário:
1. Gerencie e armazene um valor nonce para o parâmetro state.
2. Armazene o estado do usuário em um armazenamento de dados local usando o nonce como sua chave.
3. Inclua o valor nonce como o parâmetro state no URL de autorização.
4. Quando o usuário for autenticado e redirecionado para o URL de redirecionamento, valide o parâmetro state e use-o como a chave para recuperar o estado do usuário que foi armazenado.
5. Depois, redirecione o usuário conforme necessário (por exemplo, redirecionar novamente para um URL específico do usuário).
2. A HubSpot solicita o consentimento do usuário
O HubSpot exibe uma janela de consentimento para o usuário mostrando o nome do aplicativo e uma descrição resumida dos serviços de API do HubSpot a que está solicitando permissão de acesso. O usuário pode conceder acesso ao aplicativo.
Observação: o usuário que está instalando o aplicativo deve ter acesso a todos os escopos solicitados. Se ele não tiver o acesso exigido, a instalação falhará e ele será direcionado a uma página de erro. Se esta página de erro de permissões for exibida para um usuário, ele precisará ser um Superadministrador para instalar o aplicativo.
Neste estágio, seu aplicativo não faz nada. Assim que o acesso for concedido, o servidor OAuth 2.0 da HubSpot enviará uma solicitação para o URI de retorno definido no URL de autorização.
3. Manipule a resposta do servidor OAuth
Depois que o usuário concluir a solicitação de consentimento na Etapa 2, o servidor OAuth 2.0 enviará uma solicitação GET para o URI especificado em seu URL de autenticação. Se não houver problemas e o usuário aprovar a solicitação de acesso, a solicitação para o URI de redirecionamento será devolvida com um parâmetro de consulta code anexado. Se o usuário não conceder acesso, nenhuma solicitação será enviada.
Exemplo:
app.get('/oauth-callback', async (req, res) => {
if (req.query.code) {
// Handle the received code
}
});
4. Código de autorização de troca para tokens
Após seu aplicativo receber um código de autorização do servidor OAuth 2.0, ele poderá trocar esse código para um token de acesso e atualização enviando uma solicitação POST codificada por formulário para https://api.hubapi.com/oauth/v1/token com os valores mostrados abaixo. Para obter informações mais detalhadas sobre essa etapa, reserve um tempo para ler este documento de referência.
| Parâmetro | Descrição | Exemplo |
|---|
grant_type | Deve ser authorization_code | authorization_code |
client_id | ID do cliente de seu aplicativo | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
client_secret | O segredo do cliente de seu aplicativo | 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d |
redirect_uri | O URI de redirecionamento de quando o usuário autorizou seu aplicativo | https://www.example.com/auth-callback |
code | O código de autorização recebido do servidor OAuth 2.0 | 5771f587-2fe7-40e8-8784-042fb4bc2c31 |
Exemplo:
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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
Usando tokens OAuth
Assim que o fluxo de código de autorização for concluído, seu aplicativo estará autorizado a fazer solicitações em nome do usuário. Para fazer isso, forneça o token como um token bearer no cabeçalho HTTP Authorization. Detalhes específicos podem ser encontrados no documento de referência.
Exemplo:
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
}
);
Atualizando tokens OAuth
Os tokens de acesso OAuth expiram periodicamente. A finalidade é garantir que, se ele estiver comprometido, os participantes só terão acesso por um curto período. O tempo de vida útil do token em segundos é especificado no campo expires_in quando um código de autorização é trocado para um token de acesso.
Seu aplicativo pode trocar o token de atualização recebido por um novo token de acesso enviando uma solicitação POST para https://api.hubapi.com/oauth/v1/token com os valores abaixo. Para obter informações mais detalhadas sobre essa etapa, consulte o documento de referência.
| Parâmetro | Descrição | Exemplo |
|---|
grant_type | Deve ser refresh_token | refresh_token |
client_id | ID do cliente de seu aplicativo | 7fff1e36-2d40-4ae1-bbb1-5266d59564fb |
client_secret | O segredo do cliente de seu aplicativo | 7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d |
redirect_uri | O URI de redirecionamento de quando o usuário autorizou seu aplicativo | https://www.example.com/auth-callback |
refresh_token | O token de atualização recebeu quando o usuário autorizou seu aplicativo | b9443019-30fe-4df1-a67e-3d75cbd0f726 |
Exemplo:
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
}
{
"refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
"access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
"expires_in": 1800
}
Artigos relacionados
Métodos de Autenticação no HubSpot
Trabalhando com o OAuth
Gerenciar tokens
