Se você está criando a Zendesk Developer Platform, é provável que tenha encontrado erros de 401 ou 403 em algum momento. Esses dois códigos de status respondem a uma grande porcentagem de solicitações de API com falha que vemos de desenvolvedores, especialmente no início do ciclo de vida de uma integração.

Embora os dois erros estejam relacionados ao controle de acesso, eles falham por motivos muito diferentes e exigem diferentes abordagens de depuração. Tratá-los como intercambiáveis geralmente resulta em tempo perdido e repetidas solicitações malsucedidas.

Nesta publicação, abordaremos como os erros 401 e 403 funcionam no Zendesk, como diagnosticá-los rapidamente e como corrigir com confiança usando exemplos práticos e etapas de solução de problemas.

O que você aprenderá

Ao final desta publicação, você entenderá:

  • A diferença entre 401 não autorizado e 403 proibido no Zendesk
  • Como autenticar corretamente usando tokens da API, tokens de acesso OAuth e JWTs
  • Como os escopos OAuth afetam a autorização
  • Como diagnosticar cabeçalhos malformados, subdomínios incorretos e credenciais expiradas

 

Entender 401 vs 403

Embora os dois códigos de status estejam relacionados ao controle de acesso, eles falham em diferentes estágios do processamento de solicitações.

401 Não autorizado

Uma resposta 401 significa que a API do Zendesk não conseguiu autenticar a solicitação. A Zendesk não conseguiu determinar quem é o chamador, então não tenta avaliar permissões ou lógica de negócios.

As causas comuns incluem:

  • Cabeçalhos de autorização ausentes ou malformados
  • Codificação Base64 incorreta para a Autenticação básica
  • Formatação incorreta de e-mail e token
  • Tokens da API expirados ou revogados
  • Uso de tokens OAuth em um cabeçalho de Auth básico
  • JWTs inválidos ou expirados para mensagens

Se você receber um erro 401, concentre-se primeiro em como a solicitação é autenticada, não no que a solicitação está tentando fazer.

403 Proibido

Uma resposta 403 significa que a solicitação foi autenticada com êxito, mas a identidade autenticada não tem permissão para executar a ação solicitada.

As causas típicas incluem:

  • Tokens OAuth sem escopos obrigatórios
  • Uso de credenciais de usuário final para chamar pontos de extremidade apenas para agentes
  • Tentativa de acesso a recursos pertencentes a outra marca
  • Restrições de IP ativadas na conta
  • Contas de agentes suspensas ou com downgrade

Se você receber um erro 403, a autenticação está funcionando corretamente. O problema é autorização.

 

Um fluxo de diagnóstico rápido

Ao depurar problemas de acesso, a maneira mais rápida é isolar o problema passo a passo.

Comece testando sua solicitação com a curl. Se a solicitação de curl falhar, é provável que o problema seja com as credenciais ou a configuração da conta, não com o código do aplicativo.

Em seguida, confirme que você está chamando o subdomínio do Zendesk correto. As credenciais são definidas para um ambiente específico e os tokens de sandbox e de produção não são intercambiáveis.

Em seguida, verifique se você está usando o método de autenticação correto. Misturar a autenticação Basic Auth, OAuth e JWT é uma fonte comum de falhas.

Verifique a função do usuário autenticado. Muitos pontos de extremidade exigem permissões de agente ou administrador, mesmo que a autenticação seja bem-sucedida.

Se você estiver usando OAuth, confirme se o token inclui os escopos exigidos pelo ponto de extremidade.

Por fim, considere onde a solicitação está sendo executada. As solicitações de origem do navegador costumam ser bloqueadas pelas políticas de Compartilhamento de recursos entre navegadores (CORS) ao usar o token da API Basic Auth ou outros fluxos do lado do cliente sem suporte. Se você precisar ligar para a API de um navegador, use um fluxo OAuth com suporte para CORS ou encaminhe solicitações por meio de um serviço de back-end ou um aplicativo do Zendesk usando o cliente ZAF. Para obter mais informações sobre solicitações de CORS, consulte Fazer solicitações de CORS do lado do cliente para a API de tickets. 

 

Autenticação correta

A autenticação acontece antes de qualquer verificação de permissão ou lógica de negócios. Se a autenticação falhar, o Zendesk não poderá associar a solicitação a um usuário ou integração e retornará um erro 401.

O Zendesk oferece suporte a vários métodos de autenticação, cada um com requisitos de formatação rigorosos.

Autenticação do token da API

Os tokens da API usam a Autenticação básica, onde o nome de usuário inclui o sufixo /token.

O formato correto é:

curl -v \
  -u "agent@example.com/token:YOUR_API_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/tickets.json"

Um erro comum que resulta em um erro 401 é omitir o sufixo /token:

emailAddress:APITOKEN

No Node.js, um exemplo funcionando tem esta aparência:

import fetch from "node-fetch";
import btoa from "btoa";

const subdomain = "your_subdomain";
const email = "agent@example.com";
const token = process.env.API_TOKEN;

const response = await fetch(
  `https://${subdomain}.zendesk.com/api/v2/users/me.json`,
  {
    headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.status, await response.text());

 

Autenticação OAuth

Os tokens de acesso OAuth são normalmente usados para integrações que exigem credenciais de longa duração ou controle de permissões detalhado. Os tokens OAuth devem ser enviados usando o esquema de autenticação de portador. O formato correto do cabeçalho é:

Authorization: Bearer ACCESS_TOKEN

Exemplo de solicitação usando curl:

curl \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"

No Node.js, um exemplo funcionando tem esta aparência:

import fetch from "node-fetch";

const subdomain = process.env.SUBDOMAIN;
const token = process.env.OAUTH_TOKEN;

const url = `https://${subdomain}.zendesk.com/api/v2/users/me.json`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

console.log(response.status, await response.text());

Uma causa comum de erros 401 Não autorizados ao usar o OAuth é o envio de um token de acesso válido com o esquema de autenticação errado. Nesse caso, o Zendesk não consegue autenticar a solicitação e retorna um 401 antes de avaliar escopos ou permissões.

Os tokens OAuth também introduzem o conceito de escopos, que definem explicitamente quais ações o token tem permissão para executar. Um token pode autenticar com êxito, mas ainda retornar uma resposta 403 Proibida se não tiver os escopos exigidos pelo ponto de extremidade sendo chamado.

Por exemplo, um token com tickets:read pode buscar dados do ticket, mas não pode criar ou atualizar tickets. Tentar executar uma operação de gravação sem o escopo adequado resultará consistentemente em um erro 403. 

403: You do not have access to this resource

Se isso ocorrer, a autenticação está funcionando conforme o esperado, mas o token deve ser gerado novamente com os escopos corretos. Para obter mais informações sobre escopos, consulte Tokens OAuth para tipos de concessão.

 

Autenticação JWT para mensagens

Ao implementar o recurso de mensagens da Zendesk em aplicativos web ou móveis, a autenticação JWT é usada para identificar os usuários finais com segurança. Neste modelo, seu back-end é responsável por gerar e assinar um token da web JSON (JWT) usando o segredo configurado na Central de administração. O Zendesk valida o token antes de permitir que a sessão de mensagens seja associada a um usuário.

Ao contrário de tokens da API ou OAuth, os JWTs de mensagens exigem informações específicas de declarações e cabeçalhos que permitem que o Zendesk resolva a identidade do usuário corretamente.

No mínimo, um JWT de mensagens deve incluir:

  • Kind – o ID da chave da Central de administração do Zendesk. Isso deve ser incluído no cabeçalho de JWT, não na carga útil.
  • external_id – um identificador exclusivo para o usuário. O Zendesk usa esse valor como a chave principal ao fazer a correspondência ou criar registros de usuário.
  • scope – Deve ser definido como "user", indicando que o token é destinado à autenticação do usuário final em Mensagens.

As declarações adicionais como nome, e-mail e email_verified são opcionais e podem ser incluídas para preencher os detalhes do usuário na interface do agente ou na correspondência de identidade baseada no e-mail do Support.


Exemplo de gerador JWT do Node.js: 

import jwt from "jsonwebtoken";
const payload = {
  scope: "user",
  external_id: "user_12345",
  name: "Jane Doe",
  exp: Math.floor(Date.now() / 1000) + (5 * 60)
};

const token = jwt.sign(payload, process.env.ZENDESK_JWT_SECRET, {
	keyid: process.env.ZENDESK_KEYID,
});

console.log(token);

Se as declarações obrigatórias, como external_id ou scope, estiverem ausentes ou se o token estiver assinado com o segredo errado, o Zendesk retornará uma resposta 401 Não autorizada.


As causas comuns dos erros do 401 relacionados ao JWT incluem:

  • Uso de um segredo JWT do ambiente errado (sandbox versus produção)
  • Envio de um token expirado ou um token com declarações baseadas em tempo inválidas
  • Omissão de declarações obrigatórias como external_id ou scope 
  • Assinatura do token com um segredo incorreto ou girado
  • Envio de um JWT mal formatado ou codificado incorretamente

Ao depurar problemas de autenticação de mensagens, confirme primeiro se o token está assinado com o segredo correto e inclui as declarações obrigatórias. Se a autenticação for bem-sucedida, mas o comportamento da identidade do usuário for inesperado, inspecione os valores usados para external_id e quaisquer campos de identidade opcionais para garantir que eles sejam estáveis e consistentes em todas as sessões. Para obter mais informações, consulte Autenticação de usuários em seu aplicativo.
 

Causas comuns dos erros do 401

Uma resposta 401 significa que o Zendesk não conseguiu autenticar a solicitação e não conseguiu determinar a identidade do chamador.

Isso geralmente é causado por cabeçalhos de autorização incorretamente criados, tokens desativados ou incompatibilidades de ambiente.

Os cabeçalhos de Autenticação básica devem ter a seguinte formatação ou o equivalente:

headers: {
      'Authorization': 'Basic ' + btoa(`${email}/token:${token}`),
      'Content-Type': 'application/json'
}

Caracteres inesperados, espaços em branco ou problemas de codificação geralmente causam falhas silenciosas.

Por fim, lembre-se de que a REST API do Zendesk não oferece Support à autenticação de origem do navegador. As solicitações de JavaScript do lado do cliente falharão devido a CORS, cookies de sessão ausentes e fluxos de autenticação sem suporte. Em vez disso, use um serviço de back-end ou um aplicativo do Zendesk criado com o cliente ZAF.

 

Causas comuns dos erros do 403

Uma resposta 403 indica que o Zendesk autenticou a solicitação, mas negou o acesso devido a regras de permissão.

A causa mais comum é a falta de escopos OAuth. Por exemplo, um token com ticket:read pode buscar tickets, mas não pode criá-los ou atualizá-los. As tentativas de gravação retornam consistentemente um erro 403.

Os escopos OAuth não podem ser modificados após a criação do token. Se os escopos estiverem incorretos, um novo token deve ser gerado.

Outra fonte comum de confusão é tentar ligar para pontos de extremidade apenas para agentes usando credenciais de usuário final. Os tokens OAuth do usuário final podem funcionar para users/me, mas retornarão 403 ao ligar para pontos de extremidade restritos, como tickets, visualizações ou campos de ticket.

Outras causas frequentes incluem tokens revogados, restrições de listas de autorização de IP e limitações de acesso multimarca. Nesses casos, a solicitação é rejeitada porque as credenciais não estão mais ativas ou porque o usuário não atende a critérios de acesso específicos.

 

Uma abordagem passo a passo para a resolução de problemas

1. Validar credenciais isoladamente Em caso de dúvida, comece removendo o código do aplicativo da equação. Valide suas credenciais usando curl :

curl -v \
  -u "email/token:token" \
  "https://your_subdomain.zendesk.com/api/v2/users/me.json"
  • Se isso falhar: O problema provavelmente é uma credencial ou um problema relacionado à conta.
  • Se isso acontecer: As credenciais são válidas. O problema está dentro da lógica ou do ambiente do seu aplicativo. Mover para o estágio 2.

2. Verifique se há limitações do CORS: Se o comando curl funcionar, mas seu aplicativo do lado do cliente falhar, é provável que você esteja atingindo as restrições de CORS.

Abra o console do desenvolvedor do seu navegador e insira o erro. Se você vir um erro 401/403 acompanhado de uma mensagem do console sobre Access-Control-Allow-Origin, o navegador está bloqueando a solicitação antes que o Zendesk possa processá-la.

3. Verifique os cabeçalhos da solicitação bruta Se você estiver executando código do lado do servidor (Node.js, Python, PHP, etc.) e ainda estiver enfrentando problemas:

  • Cadastrar o cabeçalho Autorização: Imprime a cadeia de caracteres exata que seu aplicativo está enviando. Certifique-se de que não há caracteres ocultos de espaços em branco ou prefixos incorretos (por exemplo, certifique-se de que Basic versus Bearer é usado corretamente).
  • Confirmar ambiente: Confirme que seu aplicativo está segmentando o subdomínio correto. É comum segmentar acidentalmente uma URL sandbox com credenciais de produção ou vice-versa.

4. Verificar escopos e reivindicações Se a autenticação for bem-sucedida, mas você receber um 403 Proibido, seu token pode não ter as permissões necessárias.

  • Para OAuth: Verifique seus escopos atuais ligando para o ponto de extremidade /api/v2/OAuth/tokens/current. Certifique-se de que o token tenha o escopo necessário para o recurso que você está tentando acessar.

  • Para mensagens/JWT: Revale sua carga de JWT. Certifique-se de que a criança (ID da chave) corresponda à sua configuração do Zendesk e que o segredo de assinatura usado para gerar o token está correto.

     

Pensamentos finais

A maioria dos erros 401 e 403 na Plataforma do desenvolvedor do Zendesk vem de um pequeno número de configurações imprevisíveis. Depois de separar claramente as falhas de autenticação das falhas de autorização, a depuração fica significativamente mais rápida e confiável.

Ao validar credenciais com antecedência, confirmar escopos e funções e seguir uma abordagem de diagnóstico estruturado, você pode resolver esses problemas rapidamente e evitar que eles apareçam novamente na produção.

Para obter mais detalhes, consulte a documentação do Zendesk sobre o acesso por token da API, a autenticação OAuth, a Zendesk App Framework e a autenticação JWT de mensagens.

Aviso sobre a tradução: este artigo foi traduzido por um software de tradução automática para oferecer a você uma compreensão básica do conteúdo. Medidas razoáveis foram tomadas para fornecer uma tradução precisa, no entanto, a Zendesk não garante a precisão da tradução.

Em caso de dúvidas relacionadas à precisão das informações contidas no artigo traduzido, consulte a versão oficial do artigo em inglês.

Powered by Zendesk