Se você estiver criando uma integração com o Zendesk, eventualmente precisará autenticar suas solicitações de API. Embora os tokens de API funcionem para scripts simples, o OAuth é o padrão para aplicativos de produção que acessam dados do Zendesk em nome dos usuários. Ele permite que os usuários concedam permissões específicas sem compartilhar suas senhas e oferece controle refinado sobre o que seu aplicativo pode acessar.
Mas aqui está a questão: configurar o OAuth pode parecer complicado se você nunca fez isso antes. Existem redirecionamentos, códigos de autorização, escopos e segredos para gerenciar. Este guia explica todo o processo passo a passo, desde o registro do seu aplicativo até a realização da sua primeira chamada de API autenticada.
Se você estiver procurando uma abordagem mais simples, o eesel AI lida com a autenticação do Zendesk automaticamente. Você conecta sua conta uma vez e nós gerenciamos o fluxo OAuth nos bastidores. Mas se você precisar criar uma integração personalizada, continue lendo.
O que você vai precisar
Antes de começar, certifique-se de que você tem:
- Uma conta Zendesk no plano Suite Growth ou superior, ou no plano Support Professional ou superior
- Acesso de administrador à sua instância do Zendesk (ou alguém que possa concedê-lo)
- Uma compreensão básica dos conceitos do OAuth 2.0 (códigos de autorização, tokens de acesso, redirecionamentos)
- Um ambiente de desenvolvimento onde você possa testar o fluxo OAuth
Se você estiver apenas experimentando, o Zendesk oferece contas de avaliação para desenvolvimento. Você também pode revisar a documentação oficial do OAuth do Zendesk para obter os detalhes mais recentes sobre fluxos de autenticação e endpoints.
Passo 1: Registre seu cliente OAuth no Zendesk
O primeiro passo é informar o Zendesk sobre seu aplicativo. Isso cria um cliente OAuth que os usuários autorizam quando conectam seu aplicativo.
Navegue até a seção de Clientes OAuth:
- Faça login no Zendesk e vá para o Admin Center (clique no ícone de engrenagem na barra lateral)
- Selecione Apps e integrações na barra lateral esquerda
- Clique em APIs → Clientes OAuth
- Clique em Adicionar cliente OAuth no lado direito
Preencha os detalhes do cliente:
- Nome: Um nome de exibição para seu aplicativo. Os usuários veem isso ao autorizar seu aplicativo.
- Descrição: Opcional, mas ajuda os usuários a entender o que seu aplicativo faz
- Empresa: O nome da sua empresa
- Logotipo: Opcional. Envie uma imagem quadrada (JPG, GIF ou PNG) que represente seu aplicativo
- Tipo de Cliente: Escolha entre Público ou Confidencial
- Confidencial: Para aplicativos do lado do servidor onde você pode armazenar com segurança o segredo do cliente (client secret)
- Público: Para aplicativos móveis ou aplicativos JavaScript onde o segredo pode ser exposto. Estes devem usar PKCE.
- URLs de Redirecionamento: Os URLs para onde o Zendesk enviará os usuários depois que eles autorizarem seu aplicativo. Deve ser HTTPS (exceto para localhost durante o desenvolvimento). Adicione vários URLs em linhas separadas, se necessário.
Salve suas credenciais:
Depois de clicar em Salvar, o Zendesk gera um ID do Cliente (chamado de "Identificador") e um Segredo do Cliente (client secret). Copie ambos imediatamente, o segredo é exibido apenas uma vez. Se você perdê-lo, precisará gerar um novo.
Passo 2: Escolha o fluxo OAuth certo
O Zendesk suporta dois principais tipos de concessão OAuth 2.0. Escolha aquele que corresponde ao seu caso de uso.
O fluxo de código de autorização é para aplicativos voltados para o usuário. Quando um usuário deseja conectar seu aplicativo à sua conta do Zendesk, você o redireciona para a página de autorização do Zendesk. Eles fazem login, aprovam as permissões e o Zendesk os envia de volta ao seu aplicativo com um código de autorização. Seu servidor troca este código por um token de acesso (access token).
Este fluxo suporta tokens de atualização (refresh tokens), para que você possa obter novos tokens de acesso sem pedir ao usuário para reautorizar. Os tokens de acesso expiram (você pode definir isso entre 5 minutos e 2 dias), mas os tokens de atualização duram mais (7 a 90 dias).
O fluxo de credenciais do cliente é para autenticação máquina a máquina. Não há usuário envolvido. Seu aplicativo usa seu ID de cliente e segredo para obter um token de acesso diretamente. Isso funciona bem para serviços de backend que precisam acessar dados do Zendesk em uma programação.
PKCE (Proof Key for Code Exchange) adiciona segurança para clientes públicos. Se você estiver criando um aplicativo móvel ou um aplicativo de página única onde não pode armazenar com segurança um segredo do cliente, use PKCE com o fluxo de código de autorização. Ele evita ataques de interceptação de código de autorização.
Passo 3: Configure os escopos OAuth
Os escopos controlam o que seu aplicativo pode acessar no Zendesk. Seja específico, solicitando apenas as permissões que você realmente precisa, seguindo o princípio do menor privilégio e tornando os usuários mais propensos a confiar no seu aplicativo.
O Zendesk oferece três tipos principais de escopo:
- read: Acesso aos endpoints GET. Inclui permissão para carregar recursos relacionados.
- write: Acesso aos endpoints POST, PUT e DELETE para criar, atualizar e excluir recursos.
- impersonate: Permite que os administradores façam solicitações de API em nome dos usuários finais.
Você também pode solicitar escopos específicos de recursos para um controle mais preciso:
tickets:readoutickets:writeusers:readouusers:writeorganizations:readouorganizations:writemacros:readoumacros:writetriggers:readoutriggers:write
Por exemplo, se seu aplicativo só precisa ler tickets e atualizar perfis de usuário, solicite tickets:read users:write em vez de acesso read write geral.
Importante: As permissões reais de um usuário no Zendesk ainda se aplicam. Mesmo que seu escopo OAuth permita escrever tickets, um usuário com acesso somente leitura não pode criar tickets através do seu aplicativo.
Passo 4: Implemente o fluxo de autorização
Veja como implementar o fluxo de código de autorização, a abordagem mais comum para aplicativos web.
Envie os usuários para o endpoint de autorização:
Redirecione os usuários para este URL com os parâmetros necessários:
https://{subdomain}.zendesk.com/oauth/authorizations/new
Inclua estes parâmetros de consulta:
response_type=code(obrigatório)client_id={your_client_id}(obrigatório)redirect_uri={your_redirect_url}(obrigatório, deve corresponder ao que você registrou)scope={requested_scopes}(obrigatório, separado por espaços)state={random_string}(recomendado, evita ataques CSRF)
Exemplo de URL:
https://yourcompany.zendesk.com/oauth/authorizations/new?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/callback&scope=read%20write&state=abc123
Lide com o redirecionamento:
Depois que o usuário aprova ou nega o acesso, o Zendesk o redireciona para seu redirect_uri com:
- Um código de autorização:
?code=7xqwtlf3rrdj8uyeb1yf&state=abc123 - Um erro:
?error=access_denied&error_description=User+denied+access
Verifique se o parâmetro state corresponde ao que você enviou e, em seguida, extraia o código. Os códigos de autorização expiram após 120 segundos, então troque-os imediatamente.
Troque o código por tokens:
Faça uma solicitação POST para o endpoint de token do Zendesk:
import requests
response = requests.post(
f'https://{subdomain}.zendesk.com/oauth/tokens',
data={
'grant_type': 'authorization_code',
'code': authorization_code,
'client_id': client_id,
'client_secret': client_secret,
'redirect_uri': redirect_uri,
'scope': 'read',
'expires_in': 172800, # 2 dias
'refresh_token_expires_in': 7776000 # 90 dias
}
)
tokens = response.json()
access_token = tokens['access_token']
refresh_token = tokens['refresh_token']
Armazene ambos os tokens com segurança. O token de acesso é o que você usará para chamadas de API. O token de atualização permite que você obtenha novos tokens de acesso quando o atual expirar.
Passo 5: Use tokens de acesso em solicitações de API
Com um token de acesso, você agora pode fazer solicitações autenticadas para a API do Zendesk.
Inclua o token no cabeçalho de Autorização:
Authorization: Bearer {access_token}
Exemplo de solicitação:
import requests
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(
f'https://{subdomain}.zendesk.com/api/v2/tickets.json',
headers=headers
)
Lide com a expiração do token:
Quando um token de acesso expira, as solicitações de API retornam um status 401 com este erro:
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
Use seu token de atualização para obter um novo token de acesso:
response = requests.post(
f'https://{subdomain}.zendesk.com/oauth/tokens',
data={
'grant_type': 'refresh_token',
'refresh_token': refresh_token,
'client_id': client_id,
'client_secret': client_secret,
'scope': 'read'
}
)
new_tokens = response.json()
Se o token de atualização também expirou, você precisará enviar o usuário através do fluxo de autorização novamente.
Problemas comuns e solução de problemas
Erros de "URI de redirecionamento inválido": O URL de redirecionamento em sua solicitação de autorização deve corresponder exatamente a um dos URLs registrados em seu cliente OAuth. Verifique se há barras finais, http vs https e diferenças de subdomínio.
Permissão de escopo negada: Lembre-se de que os escopos OAuth são limitados pelas permissões reais do usuário no Zendesk. Um agente com acesso somente leitura não pode escrever tickets, mesmo que seu escopo OAuth permita.
Segredo do cliente mostrando apenas parcialmente: O Zendesk exibe o segredo completo apenas uma vez, imediatamente após a criação. Se você não o copiou, precisará gerar um novo nas configurações do cliente OAuth.
Testando com localhost: O Zendesk permite http://localhost e http://127.0.0.1 como URLs de redirecionamento para desenvolvimento. Certifique-se de registrar o URL exato, incluindo a porta (por exemplo, http://localhost:3000/callback).
Código de autorização expirado: Os códigos são válidos apenas por 120 segundos. Se o seu usuário demorar muito para autorizar, ou se houver um atraso na sua troca de código, você receberá um erro. Comece o fluxo novamente.
Melhores práticas de segurança
Armazene segredos com segurança: Nunca codifique segredos de cliente em seu código-fonte ou os envie para o controle de versão. Use variáveis de ambiente ou um serviço de gerenciamento de segredos. A folha de dicas OWASP OAuth fornece recomendações de segurança adicionais para implementações OAuth.
Use HTTPS em todos os lugares: Todos os URLs de redirecionamento em produção devem usar HTTPS. A única exceção é localhost durante o desenvolvimento.
Implemente PKCE para clientes públicos: Se você estiver criando um aplicativo móvel ou um aplicativo baseado em navegador onde o segredo pode ser exposto, use PKCE. Gere um verificador de código, faça hash para criar um desafio de código e envie o desafio com sua solicitação de autorização.
Defina a expiração razoável do token: Tokens de vida útil mais curta são mais seguros. Para a maioria dos aplicativos, 24 horas é um bom equilíbrio entre segurança e conveniência.
Gire as credenciais regularmente: Gere periodicamente novos segredos de cliente e atualize seus aplicativos. Se você suspeitar que um segredo foi comprometido, gire-o imediatamente.
Valide o parâmetro state: Sempre verifique se o parâmetro state no redirecionamento corresponde ao que você enviou. Isso evita ataques CSRF, onde sites maliciosos enganam os usuários para autorizar acesso indesejado.
Ignore a complexidade do OAuth com o eesel AI
Criar uma integração OAuth personalizada leva tempo e manutenção contínua. Você precisa lidar com o fluxo de autorização, atualização de token, casos de erro e atualizações de segurança. Para muitas equipes, este não é o melhor uso do tempo de engenharia.
eesel AI oferece um caminho mais simples. Nosso Agente de IA se conecta à sua conta do Zendesk com um único clique. Nós lidamos com a autenticação OAuth automaticamente, para que você possa se concentrar no que importa: criar automações que realmente resolvem problemas.
Em vez de escrever código para trocar códigos de autorização e atualizar tokens, você pode:
- Treinar uma IA em seus artigos da central de ajuda e tickets anteriores
- Configurar automações que resolvem tickets de ponta a ponta
- Escalar problemas complexos para humanos com regras em inglês simples
- Executar simulações em dados históricos antes de entrar em operação
Se você estiver criando uma integração profundamente personalizada, o OAuth pode ser a escolha certa. Mas se você precisar de automação de suporte com tecnologia de IA sem a sobrecarga de engenharia, experimente o eesel AI.
Perguntas Frequentes
Compartilhe esta postagem
Article by
Stevia Putri
Stevia Putri is a marketing generalist at eesel AI, where she helps turn powerful AI tools into stories that resonate. She’s driven by curiosity, clarity, and the human side of technology.
