Qual é o meu plano?
Suite, todas as versões Team, Growth, Professional, Enterprise ou Enterprise Plus
Support Team, Professional ou Enterprise

Resumo feito por IA verificado ◀▼

Use o OAuth 2 para autenticar com segurança as solicitações de API sem armazenar senhas de usuários. Registre seu aplicativo para gerar credenciais do OAuth e implemente o fluxo do código de autorização para receber tokens de acesso. Gerencie a validade do token atualizando-o com o token de atualização.

Caminho: Central de administração > Aplicativos e integrações > APIs > Clientes OAuth

Você pode usar o OAuth 2 para autenticar todos as solicitações de API do seu aplicativo para o Zendesk. O OAuth proporciona uma maneira segura para seu aplicativo acessar os dados do Zendesk sem ter que armazenar e usar senhas de usuários do Zendesk, que são informações confidenciais.

Para usar a autenticação OAuth, você precisa registrar seu aplicativo no Zendesk. Também é necessário adicionar algumas funcionalidades ao seu aplicativo para dar suporte ao fluxo do código de autorização OAuth e atualizar os tokens de acesso expirados.

O Zendesk também dá suporte ao fluxo de tipo de concessão de credenciais do cliente, o qual permite que você crie um token de acesso usando apenas o segredo de um cliente OAuth. Esse tipo de concessão foi desenvolvido somente para clientes confidenciais e não é abordado neste artigo. Para obter mais informações, consulte Client credentials grant type na referência da API.

Os tópicos abordados neste artigo são:

  • Registro de seu aplicativo no Zendesk
  • Implementação de um fluxo de autorização OAuth em seu aplicativo
  • Substituição de tokens de acesso expirados

Tópicos relacionados:

  • Para aprender a criar um aplicativo da web que implemente um fluxo de autorização OAuth, consulte Using OAuth to authenticate Zendesk API requests in a web app.
  • Para implementar o fluxo de autorização OAuth em aplicativos do Zendesk, consulte Adição de OAuth de terceiros a um aplicativo do Support.
  • Se você não precisa que usuários concedam acesso às contas deles para o seu aplicativo, você tem a opção de usar tokens de OAuth para autenticar as solicitações da API. Consulte Creating and using OAuth access tokens with the API.

Registro de seu aplicativo no Zendesk

Você deve registrar seu aplicativo para gerar credenciais OAuth que ele pode usar para autenticar chamadas da API para o Zendesk.

Observação: esta seção descreve como configurar um cliente de OAuth para usuários de uma conta do Zendesk. Se seu aplicativo interagirá com várias contas do Zendesk, você pode solicitar um cliente de OAuth global. Um cliente de OAuth global é uma maneira segura e mais clara de realizar autenticações da API com várias instâncias do Zendesk. Para obter informações, consulte Configuração do cliente OAuth global.

Como registrar seu aplicativo

  1. Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione APIs > Clientes OAuth.
  2. Clique em Adicionar cliente OAuth no lado direito da lista de clientes OAuth.
  3. Preencha os campos a seguir para criar um cliente:
    • Nome - insira um nome para o seu aplicativo. Esse é o nome que os usuários verão quando seu aplicativo solicitar permissão de acesso e quando eles verificarem a lista de aplicativos de terceiros que têm acesso ao Zendesk deles.
    • Descrição - opcional. Essa é uma descrição breve do seu aplicativo que os usuários verão quando for solicitada a permissão de acesso.
    • Empresa - opcional. Esse é o nome da empresa que os usuários verão quando for solicitada a permissão de acesso ao seu aplicativo. Essas informações podem ajudá-los a entender para quem estão concedendo o acesso.
    • Logotipo - opcional. Esse é o logotipo que os usuários verão quando seu aplicativo solicitar permissão de acesso. A imagem pode ser um JPG, GIF ou PNG. Para obter os melhores resultados, carregue uma imagem quadrada. Ela será redimensionada para a página de autorização.
    • Identificador - o campo é preenchido automaticamente com uma versão reformatada do nome que você inseriu para seu aplicativo. Você pode alterá-lo, se desejar.
    • Tipo de cliente - Público ou Confidencial. Os clientes OAuth públicos são aplicativos executados em ambientes nos quais as credenciais não podem ser armazenadas com segurança, como aplicativos para dispositivos móveis ou web. Esses clientes são obrigados a usar PKCE. Os clientes OAuth confidenciais são executados em servidores seguros, onde as credenciais podem ser mantidas em segurança. Esses clientes podem usar PKCE, segredo do cliente ou ambos. Consulte Noções básicas sobre tipos de cliente.
    • URLs de redirecionamento - insira a URL ou as URLs que o Zendesk deverá usar para enviar a decisão do usuário de permitir acesso ao seu aplicativo. As URLs devem ser absolutas e não relativas, https (a menos que sejam localhost ou 127.0.0.1) e separadas por linhas.
  4. Clique em Salvar.

    Após a página atualizar um novo campo Segredo já-preenchido será exibido no canto inferior direito. Esse é o valor de "client_secret" especificado nas especificações do OAuth 2.0.

  5. Copie o valor do Segredo para a área de transferência e salve-o em um lugar seguro. Observação: os caracteres podem ir além da largura da caixa de texto, então certifique-se de selecionar tudo antes de copiar.
    Importante: por motivos de segurança, seu segredo é exibido por completo apenas uma vez. Após clicar em Salvar, você terá acesso apenas aos primeiros nove caracteres.
  6. Clique em Salvar.

Use o identificador exclusivo e o valor do segredo em seu aplicativo como descrito no tópico a seguir.

Noções básicas sobre tipos de cliente

Os clientes OAuth têm uma propriedade kind que pode ter um dos seguintes valores:

  • Confidencial: Os clientes OAuth confidenciais são executados em servidores seguros, onde as credenciais podem ser mantidas em segurança. Esses clientes podem usar PKCE, segredo do cliente ou ambos.
  • Público: Os clientes OAuth públicos são aplicativos executados em ambientes nos quais as credenciais não podem ser armazenadas com segurança, como aplicativos para dispositivos móveis ou web. Esses clientes devem usar PKCE.

Exemplos de clientes confidenciais são os aplicativos da web do lado do servidor. Depois que o servidor de autorização fornece os tokens ou as credenciais para o aplicativo da web, essas credenciais não ficam acessíveis externamente.

Exemplos de clientes públicos são os aplicativos móveis e JavaScript que funcionam em clientes de agente do usuário, como navegadores da web. As credenciais têm acesso fácil (e costumam estar visíveis) nesses clientes.

Em inglês, os tipos de clientes são conhecidos como "client kinds" ou "client types" nas especificações do OAuth. Para obter mais informações, consulte Client Types nas especificações do OAuth 2.0.

Essa propriedade aplica-se somente ao sistema de tickets do Zendesk Support. Não há suporte no Chat, nas conversas nem no Sell.

No momento, clientes OAuth do Zendesk existentes têm a propriedade kind definida como unknown. Esses clientes permanecem não afetados até que a propriedade kind seja atualizada para public ou confidential. Novos clientes OAuth criados na Central de administração precisam definir a propriedade kind durante a criação.

Observação: se você está usando um cliente OAuth do Zendesk existente e planeja alterar a propriedade kind para public, antes precisa implementar o PKCE. Se não fizer isso, o cliente não funcionará, pois o PKCE será exigido imediatamente.

É obrigatório definir a propriedade kind para todos os novos clientes OAuth criados na Central de administração. Embora a propriedade kind não seja obrigatória para clientes OAuth criados com o ponto de extremidade api/v2/oauth/clients endpoint, a Zendesk recomenda sua inclusão.

Implementação de um fluxo de autorização OAuth em seu aplicativo

O Zendesk oferece suporte ao fluxo de concessão de código de autorização para obter tokens de acesso. Esse fluxo é chamado de fluxo de concessão de código de autorização porque é preciso obter um código de autorização antes de solicitar um token de acesso.

O fluxo usa tokens de atualização, o que permite gerar novos tokens de acesso sem exigir outra autorização do usuário. O token de acesso pode expirar se a API fornecer um parâmetro expires_in válido, indicando uma vida útil específica para o token. Nesses casos, implemente um mecanismo para obter um novo token de acesso quando ele expirar, usando o token de atualização fornecido.

Para implementar o fluxo de concessão de código de autorização, você precisa adicionar as seguintes funcionalidades ao seu aplicativo:

  • Etapa 1 - Encaminhar o usuário para a página de autorização do Zendesk
  • Etapa 2 - Gerenciar a decisão sobre autorização do usuário
  • Etapa 3 - Obter um token de acesso do Zendesk
  • Etapa 4 - Usar o token de acesso em chamadas à API

Para aprender a criar um aplicativo da web que implemente um fluxo do código de autorização OAuth, consulte Using OAuth to authenticate Zendesk API requests in a web app.

O método de concessão do código de autorização tem suporte para Proof Key for Code Exchange (PKCE), que adiciona uma camada a mais de segurança. Para obter mais informações, consulte Using PKCE to make Zendesk OAuth access tokens more secure (Uso do PKCE para tonar os tokens de acesso do Zendesk OAuth mais seguros) na documentação do desenvolvedor.

Etapa 1 - Encaminhar o usuário para a página de autorização do Zendesk

Em primeiro lugar, seu aplicativo deve encaminhar o usuário para a página de autorização do Zendesk. A página solicita que o usuário autorize seu aplicativo a acessar o Zendesk por ele. Depois que o usuário fizer sua escolha, o Zendesk enviará a opção e algumas outras informações ao seu aplicativo.

Como encaminhar o usuário para a página de autorização do Zendesk

Adicione um link ou um botão em seu aplicativo que encaminhe o usuário para a seguinte URL: 

https://{subdomain}.zendesk.com/oauth/authorizations/new

em que {subdomain} é o seu subdomínio principal do Zendesk, não um subdomínio com mapeamento do host.

Você pode usar uma solicitação POST ou GET. Inclua os seguintes parâmetros:

  • response_type - obrigatório. O Zendesk retorna um código de autorização em resposta, por isso especifique code como o tipo de resposta. Exemplo: response_type=code.
  • redirect_uri - obrigatório. A URL que o Zendesk deve usar para enviar a decisão do usuário para permitir o acesso ao aplicativo. A URL deve ser absoluta e não relativa. Também deve ser segura (https), a menos que você esteja usando localhost ou 127.0.0.1.
  • client_id - obrigatório. O identificador exclusivo que você obteve quando registrou seu aplicativo no Zendesk. Consulte a seção anterior.
  • scope - obrigatório. Uma lista de escopos separados por espaços que controla o acesso aos recursos do Zendesk. Você pode solicitar acesso de leitura, gravação ou representação de todos os recursos ou de recursos específicos. Consulte Configuração do escopo.
  • state - cadeia de caracteres arbitrária incluída na resposta do Zendesk depois que o usuário decide se deseja ou não conceder acesso. Você pode usar o parâmetro para se proteger contra ataques de falsificação de solicitações entre sites (CSRF). Em um ataque de CSRF, o usuário final é enganado para clicar em um link que realiza uma ação em um aplicativo web no qual o usuário final ainda está autenticado. Para se proteger contra esse tipo de ataque, adicione um valor ao parâmetro state e valide-o quando ele retornar.
  • code_challenge - obrigatório se estiver usando o PKCE. Uma cadeia de caracteres representando um desafio de código derivado de um verificador de código. Consulte Generating the code_challenge value (Geração do valor de code_challenge) na documentação do desenvolvedor.
  • code_challenge_method - obrigatório se estiver usando o PKCE. O método usado para derivar o desafio de código. Especifique "S256" como o valor.

Lembre-se de utilizar codificação URL nos parâmetros.

Exemplo de solicitação GET 

https://{subdomain}.zendesk.com/oauth/authorizations/new?response_type=code&redirect_uri={your_redirect_url}&client_id={your_unique_identifier}&scope=read%20write

A página de autorização do Zendesk é aberta no navegador do usuário final. Depois que o usuário tomar uma decisão, o Zendesk enviará a decisão para a URL de redirecionamento especificada na solicitação.

Configuração do escopo

Você precisa especificar um escopo para controlar o acesso do aplicativo aos recursos do Zendesk. O escopo read dá a um aplicativo acesso a pontos de extremidade GET. Ele inclui permissão para transferência local de recursos relacionados. O escopo write dá a um aplicativo acesso a pontos de extremidade POST, PUT e DELETE para criar, atualizar e apagar recursos.

Para obter mais informações sobre o escopo, consulte Tokens de OAuth para tipos de concessão.

O escopo impersonate permite que o administrador do Zendesk faça solicitações em nome de usuários finais. Consulte Solicitações da API em nome de usuários finais.

Por exemplo, o parâmetro a seguir dá a um aplicativo acesso de leitura a todos os recursos: 

"scope": "read"

O parâmetro a seguir dá acesso de leitura e gravação a todos os recursos: 

"scope": "read write"

Você pode ajustar o escopo aos seguintes recursos:

  • tickets
  • users
  • auditlogs (somente leitura)
  • organizations
  • hc
  • apps
  • triggers
  • automations
  • targets
  • webhooks
  • zis

A sintaxe é a seguinte:

"scope": "resource:scope"

Por exemplo, o parâmetro a seguir restringe um aplicativo para somente leitura de tickets: 

"scope": "tickets:read"

Para dar a um aplicativo acesso de leitura e escrita a um recurso, especifique os dois escopos: 

"scope": "users:read users:write"

Para dar a um aplicativo acesso de gravação apenas a um recurso, como organizações, e acesso de leitura a todo o resto: 

"scope": "organizations:write read"

Etapa 2 - Gerenciar a decisão sobre autorização do usuário

Seu aplicativo deve gerenciar a resposta do Zendesk que informa a decisão do usuário. A informação é contida em parâmetros de URL na URL de redirecionamento.

Se o usuário decidir autorizar o acesso ao aplicativo, a URL de redirecionamento conterá um código de autorização. Exemplo: 

{redirect_url}?code=7xqwtlf3rrdj8uyeb1yf

O código de autorização é válido apenas por 120 segundos.

Se o usuário decidir não conceder acesso ao aplicativo, a URL de redirecionamento conterá os parâmetros error e error_description que informam ao aplicativo que o usuário negou o acesso: 

{redirect_url}?error=access_denied&error_description=The+end-user+or+authorization+server+denied+the+request

Use esses valores para controlar o fluxo de seu aplicativo. Se a URL contiver o parâmetro code, obtenha um token de acesso do Zendesk conforme descrito na próxima seção. Esse é o token que será incluído nas chamadas da API ao Zendesk.

Etapa 3 - Obter um token de acesso do Zendesk

Se o seu aplicativo receber um código de autorização do Zendesk como resposta à concessão de acesso pelo usuário, seu aplicativo poderá trocá-lo por um token de acesso e um token de atualização. Para obter os tokens, faça uma solicitação POST ao ponto de extremidade Create Token Grant Type: 

https://{subdomain}.zendesk.com/oauth/tokens
Observação: não confunda esse ponto de extremidade com o ponto de extremidade Create Token na API de tokens de OAuth. Embora ambos os pontos de extremidade retornem tokens de acesso OAuth válidos, os pontos de extremidade não compartilham o mesmo caminho, formato JSON ou parâmetros de solicitação.

Inclua os seguintes parâmetros obrigatórios na solicitação:

  • grant_type - especifique “authorization_code” como valor.
  • code - use o código de autorização que você recebeu do Zendesk depois que o usuário concedeu o acesso.
  • client_id - use esse identificador exclusivo especificado em um cliente OAuth na Central de administração do Zendesk (Aplicativos e integrações > APIs > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
  • client_secret - use o segredo especificado em um cliente OAuth na Central de administração do Zendesk (Aplicativos e integrações > APIs > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.

    Se você usa os parâmetros code_challenge e code_verifier do PKCE, o client_secret não é obrigatório. Você pode usar essa característica para migrar do fluxo de concessão implícita, que não é mais recomendado devido a questões de segurança. Consulte Using PKCE to migrate from the implicit grant flow (Uso do PKCE para migrar do fluxo de concessão implícita) na documentação do desenvolvedor.

  • redirect_uri - a mesma URL de redirecionamento da etapa 1. Apenas para fins de ID.
  • scope - consulte Configuração do escopo.
  • code_verifier - obrigatório se estiver usando o PKCE. A cadeia de caracteres usada para gerar o valor de code_challenge. Consulte Generating the code_challenge value (Geração do valor de code_challenge) na documentação do desenvolvedor.
  • expires_in - tempo em segundos de validade do token de acesso. Especifique um valor entre 300 segundos (5 minutos) e 172.800 segundos (2 dias).
  • refresh_token_expires_in - tempo em segundos de validade do token de atualização. Especifique um valor entre 604.800 segundos (7 dias) e 7.776.000 segundos (90 dias).

Consulte o ponto de extremidade Create Token Grant Type na referência da API para obter mais informações.

A solicitação deve ser por meio de https e as propriedades devem ser formatados como JSON. Se você usar um aplicativo personalizado de terceiros para fazer a solicitação de API, consulte a documentação para saber o formato adequado dos valores de propriedades.

Uso da biblioteca de solicitações Python 

response = requests.post(
    f'https://{subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'authorization_code',
        'code': f'{your_code}',
        'client_id': f'{your_client_id}',
        'client_secret': f'{your_client_secret}',
        'redirect_uri': f'{your_redirect_url}',
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

Exemplo de resposta 

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f",
  "token_type": "bearer",
  "scope":"read"
}

Salve os tokens de acesso e de atualização em um armazenamento de dados seguro para reutilizá-los posteriormente.

Etapa 4 - Usar o token de acesso em chamadas à API

O aplicativo pode usar o token de acesso para realizar chamadas de API. Inclua o token em um cabeçalho de autorização HTTP com a solicitação conforme a seguinte:

Authorization: Bearer {a_valid_access_token}

Por exemplo, uma solicitação curl para listar os tickets teria a seguinte aparência: 

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

Substituição de tokens de acesso expirados

Os tokens de acesso expiram após um tempo definido. Use o token de atualização que você recebeu com o token de acesso para solicitar um novo token de acesso. Não é necessário usar o fluxo do código de autorização para obter o novo token.

Seu aplicativo deve implementar um mecanismo de fallback para lidar com tokens de acesso e de atualização expirados. Por exemplo, se o token de acesso expirou ou encontrou um erro, use um manipulador para atualizá-lo. Se o processo de atualização falhar ou não houver um token de atualização vinculado ao token de acesso, redirecione o usuário para https://{subdomain}.zendesk.com/oauth/authorizations/new para autorizar novamente seu aplicativo.

Detecção de que um token de acesso expirou

Para determinar se um token de acesso expirou, prepare seu código para procurar uma resposta 401 depois de fazer uma solicitação de API com o token. A resposta incluirá a seguinte cadeia de caracteres JSON: 

{"error":"invalid_token","error_description":"The access token provided is expired, revoked, 
 malformed or invalid for other reasons."}

Se você receber uma resposta 401, chame um manipulador para atualizar o token de acesso usando o token de atualização que você recebeu com o token de acesso.

Veja a seguir um exemplo de uso da biblioteca de solicitações Python:

url = f'https://{your_subdomain}.zendesk.com/{endpoint}'
headers = {'Authorization': f'Bearer {access_token}'}
response = requests.get(url, headers=headers)
if response.status_code == 401:     # if token has expired or is otherwise invalid
    access_token = refresh_access_token(refresh_token)
    headers['Authorization'] = f'Bearer {access_token}'
    response = requests.get(url, headers=headers)

Atualização de um token de acesso

Para atualizar um token de acesso, faça uma solicitação POST ao ponto de extremidade Create Token Grant Type: 

https://{subdomain}.zendesk.com/oauth/tokens

Inclua as seguintes propriedades no corpo da solicitação:

  • grant_type - especifique a cadeia de caracteres "refresh token" como o valor.
  • refresh_token - especifique o valor do token de atualização que você recebeu com o token de acesso.
  • client_id - use o identificador especificado no cliente OAuth na Central de administração do Zendesk (Aplicativos e integrações > APIs > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
  • client_secret - use o segredo especificado no cliente OAuth na Central de administração do Zendesk (Aplicativos e integrações > APIs > Clientes OAuth). Consulte Registro de seu aplicativo no Zendesk.
  • scope - consulte Configuração do escopo.
  • expires_in - tempo em segundos de validade do token de acesso. Especifique um valor entre 300 segundos (5 minutos) e 172.800 segundos (2 dias).
  • refresh_token_expires_in - tempo em segundos de validade do token de atualização. Especifique um valor entre 604.800 segundos (7 dias) e 7.776.000 segundos (90 dias).

Consulte o ponto de extremidade Create Token Grant Type na referência da API para obter mais informações.

Veja a seguir um exemplo de solicitação que usa a biblioteca de solicitações Python: 

response = requests.post(
    f'https://{your_subdomain}.zendesk.com/oauth/tokens',
    data={
        'grant_type': 'refresh_token',
        'refresh_token': refresh_token,
        'client_id': client_id,
        'client_secret': client_secret,
        'scope': 'read',
        'expires in': 172800,
        'refresh_token_expires_in': 800000
    }
)

A solicitação cria novos tokens de acesso e atualização enquanto invalida os anteriores. Veja um exemplo de resposta: 

Status: 201 OK

{
  "access_token": "gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo",
  "refresh_token": "31048ba4d7c601302f3173f243da835f,
  "token_type": "bearer",
  "scope": "read"
}

Salve os dois tokens em um armazenamento de dados seguro para reutilizá-los mais tarde.

Powered by Zendesk