zendesk-api-authentication-and-scopes

{
  "title": "Autenticação e escopos da API Zendesk: Um guia completo para 2026",
  "slug": "zendesk-api-authentication-and-scopes",
  "locale": "pt",
  "date": "2026-03-02",
  "updated": "2026-03-02",
  "template": "default",
  "excerpt": "Domine a autenticação da API Zendesk com este guia abrangente que cobre tokens de API, fluxos OAuth e configurações de escopo com exemplos de código práticos.",
  "categories": [
    "Zendesk",
    "Guides"
  ],
  "tags": [
    "Zendesk API",
    "OAuth",
    "API authentication",
    "developer guide",
    "Zendesk integration"
  ],
  "readTime": 11,
  "author": 16,
  "reviewer": 14,
  "seo": {
    "title": "Autenticação e escopos da API Zendesk: Um guia completo para 2026",
    "description": "Domine a autenticação da API Zendesk com este guia abrangente que cobre tokens de API, fluxos OAuth e configurações de escopo com exemplos de código práticos.",
    "image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-0684c33a-1ef3-4b86-bc2b-dc2c00de32c8"
  },
  "coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-0684c33a-1ef3-4b86-bc2b-dc2c00de32c8",
  "coverImageAlt": "Imagem do banner para autenticação e escopos da API Zendesk: Um guia completo para 2026",
  "coverImageWidth": 1920,
  "coverImageHeight": 1080,
  "faqs": {
    "heading": "Perguntas Frequentes",
    "type": "blog",
    "answerType": "html",
    "faqs": [
      {
        "question": "Qual é a diferença entre tokens de API Zendesk e tokens OAuth?",
        "answer": "Os tokens de API são mais simples de configurar, mas fornecem amplo acesso à conta e não expiram. Os tokens OAuth oferecem permissões granulares por meio de escopos, estão vinculados a usuários específicos e podem ser configurados para expirar para melhor segurança. O OAuth é recomendado para a maioria das integrações."
      },
      {
        "question": "Quantos escopos OAuth posso solicitar de uma vez?",
        "answer": "Você pode solicitar quantos escopos sua integração precisar. No entanto, siga o princípio do menor privilégio: solicite apenas os escopos que seu aplicativo realmente usa. Os usuários são mais propensos a autorizar aplicativos que solicitam permissões mínimas."
      },
      {
        "question": "Posso alterar os escopos em um token OAuth existente?",
        "answer": "Não, você não pode modificar os escopos em um token existente. Se você precisar de permissões diferentes, deverá criar um novo token com os escopos necessários. O usuário precisará reautorizar seu aplicativo."
      },
      {
        "question": "O que acontece quando um token de acesso OAuth da API Zendesk expira?",
        "answer": "Se você configurou um tempo de expiração, o token retornará um erro 401 quando usado após a expiração. Use seu token de atualização para obter um novo token de acesso sem exigir a reautorização do usuário. Se o token de atualização também estiver expirado, o usuário deverá passar pelo fluxo de autorização novamente."
      },
      {
        "question": "A autenticação por senha ainda é suportada para a API Zendesk?",
        "answer": "A autenticação por senha foi descontinuada, mas ainda funciona para implementações existentes. O Zendesk recomenda migrar para tokens de API ou OAuth para melhor segurança. Novas integrações não devem usar autenticação por senha."
      },
      {
        "question": "O que é PKCE e quando preciso usá-lo com o Zendesk OAuth?",
        "answer": "PKCE (Proof Key for Code Exchange) é uma extensão de segurança para OAuth. Você deve usá-lo para clientes públicos, como aplicativos móveis e aplicativos JavaScript, onde o segredo do cliente não pode ser mantido em segurança. Clientes confidenciais do lado do servidor podem usar PKCE, segredos do cliente ou ambos."
      }
    ],
    "supportLink": null
  }
}
---

Se você estiver criando uma integração com o Zendesk, a autenticação é seu primeiro obstáculo. Erre nisso e você gastará horas depurando erros 403 misteriosos. Acerte e você terá uma conexão segura e sustentável que simplesmente funciona.

Este guia cobre tudo o que você precisa saber sobre a autenticação da API Zendesk em 2026. Vamos percorrer os diferentes métodos de autenticação, explicar como funcionam os escopos OAuth e mostrar exatamente como implementá-los com exemplos de código em funcionamento.

Na [eesel AI](https://www.eesel.ai), criamos integrações com o Zendesk todos os dias. Vimos o que funciona, o que quebra e como evitar as armadilhas comuns que derrubam os desenvolvedores.

## Entendendo os métodos de autenticação da API Zendesk

O Zendesk oferece três maneiras de autenticar solicitações de API, embora uma esteja sendo eliminada gradualmente. Vamos detalhar suas opções.

### As três opções de autenticação

| Método | Melhor Para | Nível de Segurança | Facilidade de Configuração |
|--------|----------|----------------|---------------|
| Token de API (API Token) | Scripts internos, aplicativos de usuário único | Médio | Fácil |
| Token de Acesso OAuth (OAuth Access Token) | Aplicativos multiusuário, integrações de terceiros | Alto | Moderado |
| Senha (Autenticação Básica) (Password (Basic Auth)) | Apenas sistemas legados | Baixo | Fácil |

A autenticação por senha foi descontinuada e o Zendesk recomenda migrar para tokens de API ou OAuth. Se você estiver começando do zero, pule as senhas completamente.

### Autenticação por token de API

Os tokens de API são a opção mais simples. São senhas geradas automaticamente que você cria no Centro de Administração do Zendesk.

Veja como as credenciais funcionam:

{endereço_de_email}/token:{api_token}

Por exemplo:

jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Quando você codifica esta string em base64, seu cabeçalho de Autorização fica assim:

Authorization: Basic amRvZUBleGFtcGxlLmNvbS90b2tlbjo2d2lJQldiR2tCTW8xbVJETXVWd2t3MUVQc05rZVVqOTVQSXoyYWt2

Ou com curl:

```bash
curl https://yourdomain.zendesk.com/api/v2/users.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Limitações importantes a saber:

• Você pode ter até 256 tokens ativos (2048 se já tiver excedido 256)
• Os tokens podem se passar por qualquer usuário na conta, incluindo administradores
• Sem permissões granulares: um token tem o mesmo acesso que o usuário que o criou
• Os tokens não expiram, a menos que você os revogue manualmente

Fonte: Documentos de Segurança e Autenticação do Zendesk

Autenticação por token de acesso OAuth

OAuth é a melhor escolha para a maioria das integrações. Ele oferece controle granular sobre as permissões por meio de escopos, e os tokens são vinculados a usuários específicos, em vez de ter amplo acesso à conta.

O fluxo funciona assim:

1. Seu aplicativo redireciona o usuário para o Zendesk para autorizar o acesso
2. O usuário concede permissão e o Zendesk envia um código de autorização para seu aplicativo
3. Seu aplicativo troca o código por um token de acesso
4. Você usa o token Bearer nas solicitações da API

Veja como é uma solicitação:

curl https://yourdomain.zendesk.com/api/v2/users.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

O OAuth também oferece suporte a solicitações de API do lado do cliente de navegadores, o que os tokens de API não podem fazer devido às restrições de CORS.

Fonte: Documentação de Ajuda do Zendesk OAuth

Escopos OAuth explicados

Os escopos são o coração da segurança OAuth. Eles permitem que você solicite apenas as permissões de que seu aplicativo realmente precisa, seguindo o princípio do menor privilégio.

O que são escopos OAuth?

Pense nos escopos como autorizações de permissão. Em vez de obter acesso total a uma conta Zendesk, você solicita recursos específicos. Uma ferramenta de relatórios pode precisar apenas de acesso de leitura aos tickets. Uma ferramenta de sincronização precisa de acesso de leitura e gravação. Um painel de administração pode precisar de direitos de representação para agir em nome dos usuários.

Escopos amplos

Estes concedem acesso geral a todos os recursos:

• read: Acesso a endpoints GET e sideloading de recursos relacionados
• write: Acesso a endpoints POST, PUT e DELETE para criar, atualizar e excluir
• impersonate: Permite que os administradores façam solicitações em nome dos usuários finais

Escopos específicos de recursos

Para um controle mais preciso, você pode escopo as permissões para recursos específicos:

Recurso	Escopo de Leitura	Escopo de Gravação
Tickets	tickets:read	tickets:write
Usuários	users:read	users:write
Organizações	organizations:read	organizations:write
Central de Ajuda	hc:read	hc:write
Aplicativos	apps:read	apps:write
Acionadores	triggers:read	triggers:write
Automações	automations:read	automations:write
Webhooks	webhooks:read	webhooks:write
Macros	macros:read	macros:write
Solicitações	requests:read	requests:write
Avaliações de Satisfação	satisfaction_ratings:read	satisfaction_ratings:write
Logs de Auditoria	auditlogs:read	N/A (somente leitura)

Alguns recursos são somente gravação: any_channel:write e web_widget:write.

Fonte: Referência da API de Tokens OAuth do Zendesk

Diferenças de formato de escopo (importante!)

É aqui que os desenvolvedores costumam tropeçar. O Zendesk usa formatos diferentes, dependendo de qual endpoint você usa:

Para a API de Tokens OAuth (/api/v2/oauth/tokens):

{
  "token": {
    "client_id": 1234,
    "scopes": ["tickets:read", "users:read"]
  }
}

Para o fluxo de autorização (/oauth/tokens):

{
  "grant_type": "authorization_code",
  "scope": "tickets:read users:read"
}

O primeiro usa um array. O segundo usa uma string separada por espaços. Misture-os e você receberá erros confusos.

Implementando a autenticação OAuth

Vamos percorrer a implementação completa, passo a passo.

Passo 1: Criar um cliente OAuth

Primeiro, você precisa registrar seu aplicativo no Zendesk.

1. No Centro de Administração do Zendesk, navegue até Aplicativos e integrações > APIs > Clientes OAuth

2. Clique em Adicionar cliente OAuth

3. Preencha os detalhes:

   • Nome: Nome do seu aplicativo (os usuários veem isso ao autorizar)
   • Descrição: Breve explicação do que seu aplicativo faz
   • Tipo de cliente: Escolha Público para aplicativos móveis/SPA ou Confidencial para aplicativos do lado do servidor
   • URLs de redirecionamento: Seus URLs de retorno de chamada (devem ser HTTPS, exceto para localhost)

4. Clique em Salvar

5. Copie o valor do Segredo imediatamente. Ele é mostrado apenas uma vez.

6. Anote seu Identificador Único (este é o seu client_id)

Entendendo os tipos de cliente:

• Clientes confidenciais são executados em servidores seguros onde as credenciais podem ser protegidas. Eles podem usar PKCE, segredos do cliente ou ambos.
• Clientes públicos são executados em navegadores ou aplicativos móveis onde as credenciais são visíveis. Eles devem usar PKCE para segurança.

Se você estiver criando uma integração do lado do servidor, escolha Confidencial. Para aplicativos JavaScript ou aplicativos móveis, escolha Público.

Fonte: Documentação de Ajuda do Zendesk OAuth

Passo 2: Solicitar autorização

Envie seus usuários para a página de autorização do Zendesk:

https://{subdomínio}.zendesk.com/oauth/authorizations/new?
  response_type=code&
  redirect_uri=https://seuaplicativo.com/callback&
  client_id=seu_identificador_único&
  scope=read%20write&
  state=string_aleatória_de_estado

Parâmetros obrigatórios:

• response_type=code (você quer um código de autorização de volta)
• redirect_uri (deve corresponder ao que você registrou)
• client_id (seu identificador único)
• scope (lista de permissões separada por espaços)

Opcional, mas recomendado:

• state (string aleatória para evitar ataques CSRF)
• code_challenge e code_challenge_method=S256 (para PKCE)

O usuário vê uma página de autorização perguntando se deseja conceder acesso ao seu aplicativo. Se aprovar, o Zendesk redireciona para seu redirect_uri com um código de autorização:

https://seuaplicativo.com/callback?code=7xqwtlf3rrdj8uyeb1yf

Importante: O código de autorização expira em 120 segundos. Troque-o prontamente.

Passo 3: Trocar código por token de acesso

Faça uma solicitação POST para trocar o código:

curl https://{subdomínio}.zendesk.com/oauth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "7xqwtlf3rrdj8uyeb1yf",
    "client_id": "seu_identificador_único",
    "client_secret": "seu_segredo_do_cliente",
    "redirect_uri": "https://seuaplicativo.com/callback",
    "scope": "read write",
    "expires_in": 172800,
    "refresh_token_expires_in": 7776000
  }'

Você receberá uma resposta como:

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope": "read write",
  "expires_in": 172800,
  "refresh_token_expires_in": 7776000
}

Armazene ambos os tokens com segurança. O token de acesso é usado para chamadas de API. O token de atualização obtém um novo token de acesso quando o atual expira.

Configurações de expiração do token:

• expires_in: 300 segundos (5 minutos) a 172.800 segundos (2 dias)
• refresh_token_expires_in: 604.800 segundos (7 dias) a 7.776.000 segundos (90 dias)

Fonte: Documentação de Ajuda do Zendesk OAuth

Passo 4: Fazer solicitações de API autenticadas

Agora use seu token de acesso:

curl https://{subdomínio}.zendesk.com/api/v2/tickets.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Ou em Python:

import requests

headers = {
    "Authorization": f"Bearer {access_token}"
}
response = requests.get(
    "https://yourdomain.zendesk.com/api/v2/tickets.json",
    headers=headers
)

Ou em Node.js:

const axios = require('axios');

const response = await axios.get(
  'https://yourdomain.zendesk.com/api/v2/tickets.json',
  {
    headers: {
      'Authorization': `Bearer ${access_token}`
    }
  }
);

Quando o token de acesso expirar, use o token de atualização para obter um novo sem exigir que o usuário reautorize.

Configurações comuns de escopo por caso de uso

Diferentes integrações precisam de permissões diferentes. Aqui estão as configurações de escopo típicas para cenários comuns.

Ferramentas de relatório somente leitura

Para painéis que extraem dados de tickets sem fazer alterações:

read

Ou mais especificamente:

tickets:read users:read organizations:read

Isso dá à sua ferramenta acesso para visualizar tickets, usuários e organizações sem a capacidade de modificar nada.

Integrações de sincronização bidirecional

Para sincronizar o Zendesk com um CRM ou outros sistemas:

tickets:read tickets:write users:read users:write organizations:read organizations:write

Isso permite que você leia os dados existentes e envie atualizações de volta para o Zendesk.

Gerenciamento de conteúdo da Central de Ajuda

Para ferramentas que gerenciam artigos da base de conhecimento:

hc:read hc:write

Isso escopo as permissões apenas para o conteúdo da Central de Ajuda, mantendo os tickets e os dados do usuário fora dos limites.

Portais voltados para o cliente

Para widgets incorporados onde os usuários finais criam e visualizam seus próprios tickets:

requests:read requests:write impersonate

O escopo impersonate permite que seu aplicativo crie tickets em nome dos usuários finais sem que eles precisem de contas Zendesk.

Solução de problemas de erros de autenticação

Mesmo com a configuração correta, as coisas dão errado. Veja como corrigir os problemas mais comuns.

Erros 403 Proibido

Um 403 significa que seu token é válido, mas você não tem permissão para essa ação.

Causas:

• Escopo obrigatório ausente para o endpoint
• Formato de escopo errado (array vs string)
• A função do usuário não permite essa ação (por exemplo, agente tentando usar endpoints somente para administradores)

Correção: Verifique a documentação da API para o escopo obrigatório do endpoint. Verifique se seu token tem esse escopo usando o endpoint Mostrar Token.

Erros 401 Não Autorizado

Um 401 significa que seu token é inválido, expirou ou está malformado.

Causas:

• O token expirou (se você definiu uma expiração)
• O token foi revogado pelo usuário ou por um administrador
• O formato do token está errado (falta o prefixo "Bearer", por exemplo)

Correção: Atualize o token se você tiver um token de atualização. Caso contrário, redirecione o usuário pelo fluxo de autorização novamente.

Erros OAuth comuns

Erro	O Que Significa	Como Corrigir
invalid_grant	Código de autorização expirou ou já foi usado	Obtenha um novo código de autorização (eles expiram em 120 segundos)
redirect_uri_mismatch	O URL de redirecionamento não corresponde ao URL registrado	Verifique se há correspondência exata, incluindo protocolo e barras finais
invalid_scope	O escopo solicitado não existe	Verifique a ortografia e o formato dos nomes de escopo
invalid_client	O ID do cliente ou o segredo está errado	Verifique as credenciais no Centro de Administração

Fonte: Documentação de Ajuda do Zendesk OAuth

Melhores práticas de segurança para autenticação da API Zendesk

Fazer a autenticação funcionar é o primeiro passo. Mantê-la segura é contínuo.

Gerenciamento de tokens

• Armazene tokens criptografados: Nunca armazene tokens em texto simples ou os envie para repositórios de código
• Implemente rotação automática: Atualize os tokens antes que expirem para evitar interrupções no serviço
• Exclua tokens não utilizados: Revogue tokens para integrações que você não usa mais
• Monitore o uso de tokens: O Zendesk rastreia quando os tokens são usados. Fique atento a atividades inesperadas

Seleção de escopo

• Solicite escopos mínimos: Solicite apenas as permissões que seu aplicativo realmente precisa
• Revise as permissões concedidas: Audite periodicamente quais escopos seus tokens têm
• Documente os requisitos de escopo: Mantenha um registro de por que cada escopo é necessário para conformidade

Segurança da integração

• Use HTTPS para todas as solicitações: A API Zendesk é somente SSL e requer TLS 1.2
• Implemente PKCE para clientes públicos: Necessário para aplicativos móveis e baseados em navegador
• Valide os parâmetros de estado: Sempre verifique se o parâmetro de estado corresponde ao que você enviou para evitar ataques CSRF
• Suporte SNI: Seu cliente HTTP deve suportar a extensão TLS de Indicação de Nome do Servidor

Fonte: Documentos de Segurança e Autenticação do Zendesk

Criando integrações Zendesk seguras com eesel AI

Se tudo isso parece muito para gerenciar, você não está sozinho. A autenticação é uma das partes mais propensas a erros da criação de integrações Zendesk.

Na eesel AI, lidamos com o OAuth do Zendesk com segurança para que você não precise se preocupar com o gerenciamento de tokens, a configuração de escopo ou a lógica de atualização. Nossa integração Zendesk vem com escopos pré-configurados que seguem o princípio do menor privilégio, atualização automática de tokens e tratamento de erros integrado para problemas comuns de autenticação.

Também oferecemos um Agente de IA que pode trabalhar com seus dados do Zendesk para automatizar fluxos de trabalho de suporte. Ele se conecta através do mesmo fluxo OAuth seguro, com escopos limitados exatamente ao que a automação precisa.

Se você mesmo construir ou usar uma plataforma como a nossa, a chave é acertar a autenticação desde o início. Uma base segura torna todo o resto mais fácil.

Se você mesmo construir ou usar uma plataforma como a nossa, a chave é acertar a autenticação desde o início. Uma base segura torna todo o resto mais fácil.