Migração de API Tokens para OAuth 2.0

📢 O que está acontecendo?

A Zendesk anunciou a descontinuação da autenticação por meio de API Tokens tradicionais, utilizados por aplicações e integrações para realizar chamadas às APIs da plataforma.

Com essa mudança, todas as integrações que utilizam exclusivamente esse modelo de autenticação precisarão ser adaptadas para utilizar OAuth 2.0.

O objetivo é fortalecer a segurança, proporcionar maior controle sobre as permissões concedidas às aplicações e reduzir os riscos associados ao uso de credenciais permanentes.

📅 Cronograma da mudança

A transição está dividida em três etapas:

🎯 Quem será impactado?

Clientes que possuem aplicações, sistemas ou processos automatizados utilizando API Tokens tradicionais para acessar os serviços do Zendesk.

Importante: integrações que já utilizam OAuth 2.0 não precisam ser migradas novamente por causa dessa mudança específica. É necessário verificar o método de autenticação efetivamente utilizado por cada aplicação.

🔐 O que é OAuth 2.0?

OAuth 2.0 é um protocolo de autorização que permite que aplicações acessem recursos do Zendesk sem precisar utilizar um API Token tradicional em todas as requisições.

Diferentemente dos API Tokens tradicionais, os Access Tokens possuem validade limitada. A aplicação deverá estar preparada para renovar ou solicitar novos tokens automaticamente.

⚙️ Qual fluxo OAuth devo utilizar?

A Zendesk disponibiliza dois fluxos principais. A escolha depende de como sua aplicação funciona.

🛠️ Como realizar a migração?

Etapa 1 – Identifique os API Tokens existentes

Acesse o Admin Center e navegue até:

Identifique os tokens ativos e verifique quais aplicações utilizam cada credencial.

Consulte também os códigos-fonte, variáveis de ambiente, arquivos de configuração, ferramentas de automação e serviços externos.

Etapa 2 – Registre um cliente OAuth

No Admin Center, acesse:

Selecione Add OAuth Client e configure as informações da aplicação:

• Name: nome da integração.
• Description: descrição da finalidade da aplicação.
• Client Kind: Public ou Confidential, conforme o ambiente.
• Redirect URLs: endereço de retorno, quando exigido pelo fluxo.
• Scopes: permissões necessárias para a integração.

Após salvar, armazene o Identifier (Client ID) e o Secret (Client Secret), quando aplicável, em local seguro. O Secret é exibido integralmente apenas uma vez.

Etapa 3 – Configure as permissões (Scopes)

Defina quais recursos a aplicação poderá acessar e quais operações poderá executar.

Por exemplo:

Esse é apenas um exemplo. As permissões devem ser definidas de acordo com os endpoints realmente utilizados pela aplicação.

Recomendamos sempre aplicar o princípio do menor privilégio, concedendo somente os acessos necessários.

Etapa 4 – Implemente a autenticação OAuth

Atualize sua aplicação para solicitar um Access Token utilizando o fluxo escolhido.

O endpoint utilizado para a obtenção de tokens é:

A requisição deverá conter os parâmetros correspondentes ao fluxo OAuth escolhido, incluindo Client ID, Client Secret quando aplicável, Grant Type e Scopes.

Etapa 5 – Atualize as chamadas às APIs

Com o Access Token obtido, substitua a autenticação antiga pelo cabeçalho HTTP Authorization com o tipo Bearer.

Authorization: Basic BASE64(email/token:API_TOKEN)

Authorization: Bearer ACCESS_TOKEN

Etapa 6 – Implemente a renovação automática

O Access Token possui prazo de validade. Sua aplicação deverá controlar sua expiração e implementar a renovação ou obtenção de um novo token, conforme o fluxo utilizado.

• Authorization Code: utilize o Refresh Token para solicitar um novo par de tokens.
• Client Credentials: solicite um novo Access Token utilizando novamente o Client ID e Client Secret.

Importante: no Authorization Code, quando a renovação retornar um novo Refresh Token, armazene-o imediatamente. O anterior deixa de funcionar após a renovação bem-sucedida.

Etapa 7 – Realize os testes

Antes de desativar qualquer integração antiga, valide as principais operações:

• Consultar tickets.
• Criar e atualizar tickets.
• Consultar e atualizar usuários.
• Consultar organizações.
• Executar os processos automatizados.
• Validar a renovação dos tokens.
• Verificar logs, permissões e eventuais erros de autenticação.

💻 Exemplo de chamada autenticada

Após obter o Access Token, uma chamada à API de tickets poderá ser realizada da seguinte forma:

GET https://SEU_SUBDOMINIO.zendesk.com/api/v2/tickets.json

Authorization: Bearer SEU_ACCESS_TOKEN
Content-Type: application/json

O exemplo demonstra apenas a autenticação. Os endpoints e as permissões devem ser ajustados de acordo com as necessidades de cada integração.

🛡️ Boas práticas de segurança

📚 Documentação oficial da Zendesk

Para aprofundar os conhecimentos e consultar os exemplos técnicos, disponibilizamos os principais materiais oficiais:

✅ Checklist para a migração

Utilize esta lista para acompanhar as atividades necessárias:

Conteúdo elaborado com base na documentação oficial da Zendesk.
As orientações técnicas e os prazos podem ser atualizados pela Zendesk.