Se você cria no Zendesk Developer Platform, provavelmente encontrou erros 401 ou 403. Esses códigos de status contam com muitas 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 diferentes motivos e exigem abordagens diferentes. Se você os trata como intercambiáveis, muitas vezes pode perder tempo e gerar solicitações reprovadas repetidas.

O que você aprenderá

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

  • A diferença entre erros 401 Não autorizado e 403 Proibido no Zendesk
  • Como diagnosticar os erros rapidamente
  • Como autenticar corretamente com tokens de API, tokens de acesso OAuth e JWTs (JSON Web Tokens)
  • Como os escopos OAuth afetam a autorização
  • Como diagnosticar cabeçalhos malformados, subdomínios incorretos e credenciais expiradas
  • Como corrigir os erros com confiança por meio de exemplos práticos e etapas de solução de problemas

Diferença entre erros 401 e 403

Ambos os códigos de status estão relacionados ao controle de acesso, mas falham em diferentes estágios do processo de solicitação.

401 Não autorizado

Uma resposta 401 significa que a API do Zendesk não pode autenticar a solicitação. O Zendesk não consegue identificar o chamador, portanto, ele não avalia as permissões nem a lógica de negócios.

As causas comuns incluem:

  • Cabeçalhos de autorização ausentes ou malformados
  • Codificação incorreta do Base64 para a autenticação básica
  • Formato de e-mail e token incorreto
  • Tokens de API expirados ou revogados
  • Tokens OAuth em um cabeçalho de autenticação básica
  • JWTs inválidos ou expirados para mensagens

Se você receber um erro 401, concentre-se em como a solicitação se autentica, não no que a solicitação tenta fazer.

403 Proibido

Uma resposta 403 significa que o Zendesk autenticou a solicitação, mas a identidade autenticada não tem permissão para executar a ação solicitada.

As causas comuns incluem:

  • Tokens OAuth sem os escopos necessários
  • Credenciais de usuário final em relação a pontos de extremidade apenas para agentes
  • Acesso a recursos que pertencem a outra marca
  • Regras da lista de autorização de IP da conta
  • Contas de agentes suspensas ou que sofreram downgrade

Se você receber um erro 403, a autenticação é bem-sucedida. O problema é a autorização.

Um fluxo de diagnóstico rápido

Quando você depura problemas de acesso, a maneira mais rápida é isolar o problema passo a passo.

  1. Comece com um teste curl. Se a solicitação de curl falhar, o problema provavelmente envolve credenciais ou configuração da conta, não o código do aplicativo.
  2. Confirme que você chamou o subdomínio do Zendesk correto. Os escopos das credenciais para um ambiente específico e os tokens de sandbox e de produção não se trocam.
  3. Verifique se você usa o método de autenticação correto. As misturas entre a Autenticação básica, OAuth e JWT geralmente causam falhas.
  4. 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
  5. Se você usa OAuth, confirme se o token inclui os escopos que o ponto de extremidade requer
  6. Por último, considere onde a solicitação é executada. As solicitações de origem do navegador geralmente falham devido às políticas de Compartilhamento de recursos de origem cruzada (CORS) quando você usa o token da API Autenticação básica ou outros fluxos do lado do cliente sem suporte. Se você precisa ligar para a API de um navegador, use um fluxo OAuth com suporte para CORS, encaminhe solicitações por meio de um serviço de back-end ou use um aplicativo do Zendesk com o cliente ZAF. Para obter mais informações sobre solicitações de CORS, consulte Transformação de solicitações de CORS do lado do cliente na API de gerenciamento de tickets.

Como autenticar corretamente

A autenticação é executada 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 de 401.

O Zendesk oferece suporte a vários métodos de autenticação, cada um com regras de formato rígidas.

Autenticação do token da API

Os tokens da API usam a autenticação básica e o nome de usuário deve incluir o sufixo /token.

O formato correto é:

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

Um erro comum que retorna um erro 401 é a omissão do sufixo /token:

emailAddress:APITOKEN

Um exemplo do Node.js:

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

As integrações que precisam de credenciais de longa duração ou controle de permissões finas costumam usar OAuth. Envie tokens de acesso OAuth com o esquema de portador. Use este cabeçalho:

Authorization: Bearer ACCESS_TOKEN

Exemplo de solicitação com curl:

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

Um exemplo do Node.js:

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 401 Não autorizado com OAuth é um token de acesso válido enviado com o esquema errado. Nesse caso, o Zendesk não pode autenticar a solicitação e retorna um 401 antes de avaliar os escopos ou permissões.

Os tokens OAuth também usam scopos que definem ações permitidas. Um token pode autenticar e ainda retornar 403 Proibido se não tiver os escopos exigidos pelo ponto de extremidade.

Por exemplo, um token com tickets:read pode buscar dados de ticket, mas não pode criar ou atualizar tickets. Uma tentativa de gravação sem o escopo correto sempre retorna um erro 403.

403: You do not have access to this resource

Se isso ocorrer, a autenticação funciona, mas você deve gerar novamente o token com os escopos corretos. Para obter detalhes sobre o escopo, consulte Tokens OAuth para tipos de concessão.

Como usar a autenticação JWT para mensagens

O recurso de mensagens da Zendesk em aplicativos para dispositivos móveis ou na web usa JWT para identificar usuários finais. Seu back-end deve assinar um token da web JSON com o segredo da Central de administração. O Zendesk valida o token antes de associar a sessão de mensagens a um usuário.

Os JWTs de mensagens precisam de valores específicos de cabeçalho e declaração para que o Zendesk possa resolver a identidade do usuário.

Um JWT de mensagens deve incluir, no mínimo:

  • kid – O ID da chave da Central de administração no cabeçalho do JWT, não na carga útil
  • external_id – Um identificador exclusivo para o usuário
  • scope – O valor "user" para autenticação de usuário final em mensagens

Reivindicações opcionais como nome, email e email_verified podem preencher os detalhes do usuário na interface do agente e Support correspondência de identidade baseada em email.

Exemplo de gerador de 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 você assinar com o segredo errado, o Zendesk retornará 401 Não autorizado.

Causas comuns do 401 com JWT:

  • Um segredo JWT do ambiente errado (sandbox versus produção)
  • Um token expirado ou uma reivindicação baseada em tempo inválida
  • As declarações obrigatórias, como external_id ou scope, não estão presentes
  • Um token assinado com um segredo incorreto ou girado
  • Um JWT malformado ou codificado incorretamente

Para depurar a autenticação de mensagens, primeiro confirme o segredo correto e as declarações obrigatórias. Se a autenticação for bem-sucedida, mas o comportamento da identidade parecer desativado, verifique valores estáveis e consistentes para external_id e quaisquer campos de identidade opcionais nas sessões. Para obter mais informações, consulte Autenticação de usuários em seu aplicativo.

Causas comuns de erros de 401

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

Cabeçalhos de autorização incorretos, tokens desativados ou incompatibilidades de ambiente causam a maioria das respostas do 401.

Formatar cabeçalhos de autenticação básica como este:

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.

A REST API do Zendesk não Support autenticação de origem do navegador. As solicitações de JavaScript do lado do cliente falham 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 com o cliente ZAF.

Causas comuns dos erros de 403

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

A falta de escopos OAuth causa a maioria das respostas 403. Por exemplo, um token com tickets:read pode buscar tickets, mas não pode criá-los ou atualizá-los. Uma tentativa de gravação sempre retorna um erro 403.

Não é possível modificar os escopos OAuth após a criação do token. Se os escopos estiverem errados, gere um novo token.

Outra armadilha comum: uma chamada para pontos de extremidade apenas para agentes com credenciais de usuário final. Os tokens OAuth do usuário final podem ligar para usuários/me, mas retornam 403 para pontos de extremidade restritos, como tickets, visualizações ou campos de ticket.

Outras causas incluem tokens revogados, regras de lista de autorização de IP e limites de acesso Multimarca. Nesses casos, o Zendesk rejeita a solicitação porque as credenciais estão inativas ou o usuário não atende aos critérios de acesso.

Uma abordagem de solução de problemas passo a passo

1. Validar credenciais isoladamente:

curl -v \
  -u "email/token:token" \
  "https://yoursubdomain.zendesk.com/api/v2/users/me.json"
  • Se isso falhar: O problema provavelmente envolve credenciais ou a conta.
  • Se isso acontecer: As credenciais são válidas. O problema está na lógica ou no ambiente do seu aplicativo. Mover para o estágio 2.

2. Verificar se há limites de CORS:

Se a curl funcionar, mas o aplicativo do lado do cliente falhar, é provável que você tenha atingido as restrições de CORS. Abra o console do desenvolvedor do navegador e analise o erro. Se você vir um 401/403 com uma mensagem Access-Control-Allow-Origin, o navegador bloqueia a solicitação antes que o Zendesk possa processá-la.

3. Inspecionar cabeçalhos brutos de solicitação:

  • Entrar no cabeçalho Autorização: Imprima a cadeia de caracteres exata que seu aplicativo envia. Confirme que não há espaços em branco ocultos e corrija prefixos como Basic ou Bearer.
  • Verificar ambiente: Confirme se seu aplicativo tem como alvo o subdomínio correto. Muitas equipes têm como alvo uma URL sandbox com credenciais de produção ou vice-versa.

4. Verificar escopos e declarações:

  • Para OAuth: Ligar para /api/v2/OAuth/tokens/current para listar os escopos atuais. Confirme se o token tem o escopo exigido pelo recurso.
  • Para mensagens/JWT: Revale sua carga de JWT. Confirme se o filho (ID da chave) corresponde à sua configuração do Zendesk e se você usou o segredo de assinatura correto.

Pensamentos finais

A maioria dos erros 401 e 403 na Zendesk Developer Platform vem de um pequeno conjunto de configurações imprevisíveis. Separe a autenticação da autorização para acelerar o diagnóstico e aumentar a confiabilidade.

Valide suas credenciais com antecedência, confirme escopos e funções e siga uma abordagem de diagnóstico estruturado para resolver problemas rapidamente e evitar repetições na produção.

Para obter mais detalhes, consulte os documentos do Zendesk sobre o acesso por token da API, a autenticação OAuth, a estrutura de aplicativos do Zendesk 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