Guia do Quickstart do OAuth

Antes de começar

Antes de começar a usar o OAuth com o HubSpot, você precisará ter:

* Você precisa ser um Superadministrador para instalar um aplicativo em uma conta da HubSpot


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:

  1. O aplicativo abre uma janela do navegador para direcionar o usuário ao servidor OAuth 2.0 do HubSpot
  2. O usuário avalia as permissões solicitadas e concede acesso ao aplicativo
  3. O usuário é redirecionado de volta ao aplicativo com um código de autorização na Query String da URL
  4. 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

Observação: Todos os exemplos de código neste guia são desenvolvidos em JavaScript (Node.js)

 

Aplicativo Quickstart

Se essa é a primeira vez que você está usando a autenticação OAuth com APIs da HubSpot, consulte o Aplicativo Quickstart do OAuth 2.0 desenvolvido em Node.js. Esse aplicativo de exemplo tem por finalidade ensinar você começar a usar o OAuth 2.0 o mais rápido possível. Ele demonstra todas as etapas descritas abaixo em Obtendo tokens do OAuth 2.0

Obtendo tokens do OAuth 2.0

Etapa 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 abaixo. Para obter informações mais detalhadas sobre essa etapa, leia o documento de referência.

Parâmetros de consulta do URL de autorização
Parâmetro Obrigatório? Descrição Exemplo
client_id Sim O ID do cliente identifica seu aplicativo. Encontre-o na página de configurações do seu aplicativo.

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

scope Sim Os escopos que seu aplicativo está solicitando, separados espaços codificados por URL.

contacts%20social

redirect_uri Sim O URL para o qual o usuário será redirecionado depois que ele autorizar seu aplicativo para os escopos solicitados. Para aplicativos de produção, o https é obrigatório.

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

optional_scope Não 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

Depois de criar seu URL, comece o processo do OAuth 2.0 direcionando o usuário a ele.

Exemplos

Usando um redirecionamento no 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)}`; // Redirect the user return res.redirect(authUrl);

Usando um link 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>

Etapa 2: O HubSpot solicita consentimento ao 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.

oauth_2_grant_prompt

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.

Etapa 3: Tratar a resposta do servidor OAuth 2.0

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 Query de código 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 } });

Etapa 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 }

O corpo da resposta do token será dados JSON:

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

Observação: O token de acesso expirará após o número de segundos fornecido no campo expires_in da resposta (seis horas). Para obter informações sobre como obter um novo token de acesso, consulte Atualizando tokens do OAuth 2.0.

Usando tokens do OAuth 2.0

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 de Autorização . 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 de OAuth 2.0

Os tokens de acesso do OAuth expiram periodicamente. A finalidade é garantir que, se ele estiver comprometido, os participantes só terão acesso por um curto período. A tempo de vida útil do token (por padrão, seis horas) é 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 }

O corpo da resposta do token será dados JSON:

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

O novo token de acesso pode ser usado para fazer chamadas em nome do usuário. Quando o novo token expirar, siga as mesmas etapas novamente para recuperar um novo token.