Escopos OAuth da API Zendesk: Um guia completo para desenvolvedores
Stevia Putri
Última edição February 27, 2026
Quando você está criando integrações com o Zendesk, controlar o que seu aplicativo pode e não pode fazer é fundamental. Os escopos OAuth atuam como portões de permissão, permitindo que você especifique exatamente quais partes da API Zendesk seu aplicativo pode acessar.
Ao contrário dos tokens de API, que concedem amplo acesso a toda a sua conta Zendesk, os escopos OAuth permitem que você siga o princípio do menor privilégio. Você solicita apenas as permissões de que precisa, nada mais. Isso torna suas integrações mais seguras e fáceis de auditar.
Neste guia, vamos percorrer tudo o que você precisa saber sobre os escopos OAuth da API Zendesk: o que são, quais estão disponíveis, como implementá-los e as melhores práticas para manter suas integrações seguras.
O que são os escopos OAuth da API Zendesk?
Os escopos OAuth no Zendesk são declarações de permissão que controlam o acesso aos recursos da API. Quando você cria um token OAuth, você especifica escopos que determinam quais ações seu aplicativo pode executar: ler tickets, gravar em registros de usuário, gerenciar conteúdo da central de ajuda e assim por diante.
Pense nos escopos como chaves para salas específicas em um edifício. Em vez de ter uma chave mestra que abre todas as portas (como um token de API), você solicita chaves apenas para as salas que precisa entrar. Se sua integração precisar apenas ler dados de ticket, você solicita o escopo read ou tickets:read. Você não terá acesso para excluir usuários ou modificar gatilhos.
Essa abordagem granular é importante por vários motivos:
- Segurança: Se um token for comprometido, o dano é limitado às permissões definidas no escopo
- Conformidade: Você pode demonstrar exatamente quais dados seu aplicativo acessa
- Confiança do usuário: Os usuários finais veem exatamente quais permissões estão concedendo durante a autorização OAuth
- Depuração: Quando algo quebra, você sabe exatamente quais permissões estão envolvidas
O Zendesk oferece suporte a dois formatos de escopo principais, dependendo de como você cria seus tokens. A API de Tokens OAuth usa um formato de array ("scopes": ["read"]), enquanto o endpoint de token grant-type usa uma string separada por espaços ("scope": "read write"). Abordaremos ambas as abordagens na seção de implementação. Para uma comparação mais profunda de OAuth versus tokens de API, consulte o guia de autenticação do Zendesk.
Escopos OAuth disponíveis no Zendesk
O Zendesk organiza os escopos em duas categorias: escopos amplos que se aplicam a todos os recursos e escopos específicos de recursos que visam endpoints de API individuais.
Escopos amplos
Esses três escopos controlam o acesso a todos os recursos do Zendesk:
| Escopo | Nível de Acesso | Melhor Para |
|---|---|---|
read | Endpoints GET e sideloading | Ferramentas de relatório, painéis de análise, integrações somente leitura |
write | Endpoints POST, PUT, DELETE | Ferramentas de sincronização, plataformas de automação, integrações bidirecionais |
impersonate | Solicitações em nome de usuários finais | Portais do cliente, widgets de suporte incorporados, aplicativos proxy |
O escopo impersonate merece uma menção especial. Ele permite que os administradores façam solicitações de API em nome de usuários finais, o que é útil ao criar aplicativos voltados para o cliente que precisam criar tickets ou acessar o histórico de solicitações sem expor as credenciais de administrador. Este escopo requer privilégios de administrador e deve ser usado com cuidado.
Escopos específicos de recursos
Para um controle mais granular, o Zendesk permite que você defina permissões para recursos específicos usando a sintaxe resource:scope. Aqui estão os recursos que oferecem suporte ao acesso definido no escopo:
| Recurso | Escopo de Leitura | Escopo de Gravação | Notas |
|---|---|---|---|
| tickets | tickets:read | tickets:write | Funcionalidade principal de emissão de tickets |
| users | users:read | users:write | Gerenciamento de usuários e perfis |
| organizations | organizations:read | organizations:write | Registros de organização |
| auditlogs | auditlogs:read | N/A | Somente leitura por design |
| hc (central de ajuda) | hc:read | hc:write | Artigos, categorias, seções |
| apps | apps:read | apps:write | Gerenciamento do marketplace de aplicativos |
| triggers | triggers:read | triggers:write | Automação de regras de negócios |
| automations | automations:read | automations:write | Automações baseadas em tempo |
| targets | targets:read | targets:write | Alvos de notificação |
| webhooks | webhooks:read | webhooks:write | Configuração de webhook |
| macros | macros:read | macros:write | Respostas predefinidas |
| requests | requests:read | requests:write | Interface de ticket do usuário final |
| satisfaction_ratings | satisfaction_ratings:read | satisfaction_ratings:write | Dados CSAT |
| dynamic_content | dynamic_content:read | dynamic_content:write | Itens de conteúdo dinâmico |
| any_channel | N/A | any_channel:write | Somente gravação |
| web_widget | N/A | web_widget:write | Somente gravação |
| zis | zis:read | zis:write | Zendesk Integration Services |
A flexibilidade aqui é poderosa. Você pode misturar e combinar escopos para criar conjuntos de permissões precisos. Por exemplo, "scopes": ["tickets:read", "users:write", "organizations:read"] concede acesso de leitura a tickets e organizações, além da capacidade de atualizar registros de usuário.
Sintaxe e formato do escopo OAuth
Acertar a sintaxe é importante porque o Zendesk retorna tokens mesmo com formatos de escopo inválidos, mas as chamadas de API com esses tokens falharão com erros "Forbidden".
Tokens não grant-type (array de escopos)
Ao usar a API de Tokens OAuth para criar tokens diretamente (normalmente para uso interno ou tokens criados por administradores), use o formato de array:
{
"token": {
"client_id": 1234,
"scopes": ["tickets:read", "users:read"]
}
}
Pontos chave:
- O nome do parâmetro é
scopes(plural) - O valor é um array JSON de strings
- Cada escopo é um elemento de array separado
- Endpoint:
POST /api/v2/oauth/tokens
Tokens grant-type (string de escopo)
Ao implementar o fluxo de autorização OAuth (código de autorização, token de atualização ou credenciais do cliente), use o formato de string separada por espaços:
{
"grant_type": "authorization_code",
"code": "7xqwtlf3rrdj8uyeb1yf",
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"scope": "tickets:read users:write"
}
Pontos chave:
- O nome do parâmetro é
scope(singular) - O valor é uma string separada por espaços
- Vários escopos entram na mesma string
- Endpoint:
POST /oauth/tokens
Combinações de escopo comuns
Aqui estão combinações de escopo práticas para casos de uso típicos:
Relatórios somente leitura:
"scopes": ["read"]
Gerenciamento de tickets com pesquisa de usuário:
"scopes": ["tickets:read", "tickets:write", "users:read"]
Gerenciamento de conteúdo da central de ajuda:
"scopes": ["hc:read", "hc:write", "tickets:read"]
Acesso total de administrador (use com moderação):
"scopes": ["read", "write"]
Como implementar escopos OAuth em seu aplicativo
Vamos percorrer a implementação completa, desde a criação de um cliente OAuth até a realização de sua primeira solicitação de API com escopo.
Passo 1: Crie um cliente OAuth no Zendesk
Antes de solicitar tokens com escopo, você precisa registrar seu aplicativo como um cliente OAuth no Zendesk.
-
Faça login na sua conta Zendesk como administrador
-
Navegue até Central de administração > Aplicativos e integrações > APIs > Clientes OAuth
-
Clique em Adicionar cliente OAuth
-
Preencha os campos obrigatórios:
- Nome: Nome do seu aplicativo (os usuários verão isso durante a autorização)
- Descrição: Breve descrição do que seu aplicativo faz
- Tipo de cliente: Escolha Público para aplicativos móveis/SPA, Confidencial para aplicativos do lado do servidor
- URLs de redirecionamento: Seus URLs de callback (devem ser HTTPS, exceto para localhost)
-
Clique em Salvar
-
Copie o valor do Segredo imediatamente (ele é mostrado apenas uma vez por completo)
-
Anote seu Identificador Único (este é o seu
client_id)
Importante: Se você selecionar Público como o tipo de cliente, você deve implementar PKCE (Proof Key for Code Exchange) para segurança. Clientes confidenciais podem usar PKCE, segredo do cliente ou ambos.
Passo 2: Solicite autorização com escopos
Envie seus usuários para o endpoint de autorização do Zendesk com seus escopos solicitados:
https://{subdomain}.zendesk.com/oauth/authorizations/new?
response_type=code&
redirect_uri=https://your-app.com/callback&
client_id=your_unique_identifier&
scope=read%20write&
state=random_state_string
Parâmetros obrigatórios:
response_type=code: Indica que você deseja um código de autorizaçãoredirect_uri: Deve corresponder a um dos URLs registrados na Etapa 1client_id: Identificador exclusivo do seu cliente OAuthscope: Lista separada por espaços dos escopos solicitados
Parâmetros recomendados:
state: String aleatória para evitar ataques CSRF (valide se isso corresponde quando o usuário retornar)code_challengeecode_challenge_method=S256: Obrigatório para PKCE com clientes públicos
O usuário verá uma tela de autorização listando os escopos que você está solicitando. Eles aprovarão ou negarão o acesso.
Passo 3: Troque o código de autorização pelo token de acesso
Quando o usuário aprova, o Zendesk redireciona para seu URL de callback com um código de autorização:
https://your-app.com/callback?code=7xqwtlf3rrdj8uyeb1yf&state=random_state_string
Troque este código por um token de acesso:
curl https://{subdomain}.zendesk.com/oauth/tokens \
-H "Content-Type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "7xqwtlf3rrdj8uyeb1yf",
"client_id": "your_unique_identifier",
"client_secret": "your_client_secret",
"redirect_uri": "https://your-app.com/callback",
"scope": "read write"
}'
Importante: O código de autorização expira em 120 segundos. Troque-o imediatamente.
A resposta inclui seu token de acesso e token de atualização:
{
"access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
"refresh_token": "31048ba4d7c601302f3173f243da835f",
"token_type": "bearer",
"scope": "read write",
"expires_in": 172800,
"refresh_token_expires_in": 800000
}
Passo 4: Use o token de acesso nas solicitações de API
Inclua o token em suas solicitações de API como um token Bearer:
curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
O token só funciona para endpoints que correspondem aos seus escopos. Um token com escopo tickets:read pode buscar tickets, mas não pode criá-los (isso exigiria tickets:write).
Configurações de escopo comuns para casos de uso típicos
Diferentes integrações precisam de diferentes conjuntos de permissões. Aqui estão as configurações que vemos com frequência:
Ferramentas de relatório e análise
Essas ferramentas só precisam ler dados:
"scope": "read"
Ou mais restritivo:
"scope": "tickets:read users:read organizations:read"
Integrações de sincronização bidirecional
As ferramentas de sincronização precisam ler e gravar em vários recursos:
"scope": "tickets:read tickets:write users:read users:write organizations:read organizations:write"
Gerenciamento de conteúdo da Central de Ajuda
Para gerenciar artigos da base de conhecimento:
"scope": "hc:read hc:write"
Portais voltados para o cliente
Quando seu aplicativo atua em nome de usuários finais:
"scope": "requests:read requests:write impersonate"
Ferramentas de automação e fluxo de trabalho
Para ferramentas que gerenciam regras de negócios:
"scope": "triggers:read triggers:write automations:read automations:write webhooks:read webhooks:write"
Solução de problemas de erros relacionados ao escopo
Mesmo com a implementação adequada, você encontrará erros. Veja como lidar com os mais comuns:
Erros "Forbidden" (403)
Este é o erro mais comum relacionado ao escopo. Isso significa que seu token não tem permissão para o endpoint solicitado.
Causas:
- Escopo obrigatório ausente para o endpoint
- Formato de escopo inválido (incompatibilidade de array vs string)
- A função do usuário não tem permissão (os escopos OAuth são limitados pelas permissões do usuário)
Solução: Verifique qual escopo o endpoint requer na documentação da API Zendesk e, em seguida, verifique se seu token o inclui. Lembre-se de que alguns endpoints exigem privilégios de administrador, independentemente dos escopos OAuth. Para obter mais detalhes sobre como criar e gerenciar tokens, consulte o tutorial de token OAuth do Zendesk.
401 Não autorizado
Isso indica um token expirado ou revogado:
{
"error": "invalid_token",
"error_description": "The access token provided is expired, revoked, malformed or invalid for other reasons."
}
Solução: Use seu token de atualização para obter um novo token de acesso ou redirecione o usuário pelo fluxo de autorização novamente se o token de atualização também tiver expirado.
Formato de escopo inválido
Se você passar os escopos no formato errado (array quando a string é esperada ou vice-versa), o Zendesk ainda poderá emitir um token, mas as chamadas de API falharão.
Solução: Verifique novamente qual endpoint você está usando:
/api/v2/oauth/tokensusa o formato de array"scopes": []/oauth/tokensusa o formato de string"scope": ""
Incompatibilidade de escopo vs. função
Os escopos OAuth são filtrados pela função do usuário. O token OAuth de um agente não pode acessar endpoints somente para administradores, mesmo que o token tenha escopo write.
Solução: Certifique-se de que o usuário que autoriza seu aplicativo tenha as permissões de função necessárias para os requisitos de sua integração.
Melhores práticas para segurança de escopo OAuth
Seguir estas práticas manterá suas integrações Zendesk seguras:
Solicite escopos mínimos
Solicite apenas as permissões de que você realmente precisa. Se sua integração apenas lê tickets, não solicite o escopo write. Isso limita a exposição se um token for comprometido.
Use clientes confidenciais quando possível
Aplicativos do lado do servidor devem usar clientes confidenciais com segredos do cliente. Clientes públicos (aplicativos móveis, SPAs) devem implementar PKCE.
Implemente a lógica de atualização de token
Os tokens de acesso expiram. Você vai querer construir uma lógica de atualização automática em seu aplicativo:
response = requests.get(api_url, headers=headers)
if response.status_code == 401:
new_token = refresh_access_token(refresh_token)
headers['Authorization'] = f'Bearer {new_token}'
response = requests.get(api_url, headers=headers)
Armazene tokens com segurança
Trate os tokens de acesso e os tokens de atualização como senhas. Armazene-os criptografados, nunca os registre e não os exponha no código do lado do cliente.
Valide os parâmetros de estado
Sempre inclua e valide o parâmetro state em seu fluxo OAuth para evitar ataques CSRF.
Considere usar uma plataforma de integração segura
Criar integrações OAuth com segurança requer atenção cuidadosa ao armazenamento de tokens, lógica de atualização e tratamento de erros. Se você estiver criando integrações de suporte ao cliente, considere usar uma plataforma como eesel AI que lida com o OAuth do Zendesk com segurança, com gerenciamento de escopo adequado integrado. Nosso Agente de IA se integra ao Zendesk usando os escopos mínimos necessários, seguindo o princípio do menor privilégio por padrão. Você também pode aprender mais sobre visualizar e gerenciar seus tokens OAuth na documentação do Zendesk.
Conclusão
Os escopos OAuth da API Zendesk oferecem controle preciso sobre o que suas integrações podem acessar. Ao entender os escopos disponíveis, implementá-los corretamente e seguir as melhores práticas de segurança, você pode criar integrações poderosas e seguras.
Os principais pontos a serem lembrados:
- Use escopos amplos (
read,write) para integrações simples, escopos específicos de recursos para controle granular - Combine seu formato de escopo com seu endpoint de token (array vs string)
- Sempre solicite permissões mínimas
- Lide com o vencimento do token normalmente com a lógica de atualização
- Lembre-se de que as funções de usuário restringem os escopos OAuth
Esteja você criando uma ferramenta de relatório simples ou uma sincronização bidirecional complexa, a configuração de escopo adequada é a base de uma integração Zendesk segura.
Perguntas Frequentes
Share this article
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.
