Qual é o meu plano?
Suite Qualquer plano
Caminho rápido: Central de administração > Aplicativos e integrações > Conexões > Conexões
Uma conexão permite que você armazene com segurança as credenciais da API para um serviço ou sistema como o Slack ou a Shopify. Você pode usar uma conexão para autenticar chamadas da REST API em ações de assistência automática. Você precisa ser um administrador para criar conexões.
Observação: as instruções neste artigo também se aplicam a contas que usam a etapa Fazer chamada de API do criador de bots legado.
Este artigo abrange os seguintes tópicos:
  • Saiba mais sobre conexões
  • Criação de uma conexão
  • Domínio permitido
  • Cabeçalhos HTTP para chaves da API

Saiba mais sobre conexões

Uma conexão aceita um dos seguintes métodos de autenticação da API:

  • Chave da API
  • Autenticação básica
  • Token do portador
  • OAuth 2.0

Esse método de autenticação determina o tipo de credenciais que a conexão armazena. Por exemplo, uma conexão de autenticação básica armazena um nome de usuário e uma senha. Depois de criar a conexão, você não pode alterar seu tipo de autenticação.

APIs diferentes aceitam métodos de autenticação diferentes. Para determinar o método de autenticação apropriado para uma chamada da API, consulte a documentação da API.

Cabeçalhos HTTP para tipos de autenticação

Quando você usa uma conexão para autenticar uma chamada de API em uma ação de assistência automática, o Zendesk passa as credenciais da conexão em um cabeçalho HTTP. O Zendesk determina esse cabeçalho de acordo com o tipo de autenticação da conexão.
Tipo de autenticação Cabeçalho HTTP
Chave da API Definido quando você cria a conexão. Consulte Cabeçalhos HTTP para chaves da API
Autenticação básica Authorization: Basic
Token do portador Authorization: Bearer
OAuth 2.0 O token de acesso é enviado para o serviço em Authorization: Bearer

Para obter mais informações sobre o uso de uma conexão em uma ação, consulte Criação e gerenciamento de ações para assistência automática.

Criação de um cliente OAuth

Uma conexão OAuth armazena um token de acesso OAuth 2.0 para um serviço ou sistema, como Slack, Shopify ou Zendesk.

Antes de criar uma conexão com o tipo de autenticação OAuth 2.0, você precisa configurar um cliente OAuth. Ao configurar o cliente OAuth, você precisa do ID do cliente, do segredo do cliente, da URL da autorização, da URL do token e dos escopos da interface de configuração OAuth do sistema externo ou do portal de administração. Essas credenciais são geradas durante o registro do aplicativo de cliente (como o Zendesk) com o sistema externo. As etapas exatas variam conforme o serviço externo. Se necessário, defina a URL de retorno de chamada do cliente como "https://zis.zendesk.com/api/services/zis/connections/oauth/callback".

Observação: só temos suporte para conexões com sistemas externos que são compatíveis com a estrutura de autorização OAuth 2.0.
Você pode criar clientes OAuth usando os seguintes tipos de concessão OAuth 2.0:
  • Código de autorização
  • Credenciais do cliente

O tipo de concessão token de atualização é compatível com clientes OAuth 2.0 criados utilizando um tipo de permissão código de autorização. Se a resposta do token de acesso do sistema incluir valores expires_in e refresh_token não vazios, o token de acesso será atualizado automaticamente usando o token de atualização.

As conexões OAuth 2.0 criadas com um cliente usando o tipo de concessão com credencias do cliente podem incluir um valor de expiração do token. Nesses casos, quando o token expira, um novo token de acesso é obtido utilizando o mesmo cliente OAuth.

Observação: em alguns casos, podemos atualizar o token de acesso várias vezes com um único token de atualização. Como alguns sistemas implementam mecanismos para evitar a reutilização de um token de atualização, recomendamos implementar um período de tolerância, se possível, ou, em vez disso, usar o tipo de concessão credenciais do cliente.

Como criar um cliente OAuth

  1. Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Conexões > Conexões.
  2. Insira um nome para o cliente. Não é possível alterar esse nome após criar o cliente.
  3. Insira o ID do cliente. Esse é um identificador exclusivo atribuído ao cliente OAuth, semelhante a um nome de usuário para o seu cliente.
  4. Insira o segredo do cliente. Isso funciona como uma senha para o aplicativo do seu cliente e estabelece confiança entre o Zendesk e o sistema externo.
  5. (Somente para o tipo de concessão código de autorização) Insira a URL de autorização. Isso funciona como a URL do servidor usada para receber um código de autorização.
  6. Insira a URL do token. Essa é a URL usada para receber um token de acesso.
  7. Insira uma lista de escopos padrão separados por espaço. Escopos são permissões que representam o que um aplicativo de cliente pode acessar em nome do usuário.
  8. Clique em Salvar para criar o cliente.

Criação de uma conexão

Você pode criar uma conexão na Central de administração a partir da página Conexões.

Como criar uma conexão

  1. Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Conexões > Clientes OAuth.
  2. Clique em Criar conexão.
  3. Selecione um tipo de autenticação.
  4. Insira um nome para a conexão. Não é possível alterar esse nome depois de você criar a conexão.
  5. Realize uma das seguintes ações:
    • (Chave de API, autenticação básica, Token do portador) Configure as credenciais de autenticação da conexão. A conexão usa esses detalhes para autenticar chamadas da REST API para o serviço ou o sistema.
    • (OAuth 2.0) Selecione o cliente para usar e, opcionalmente, insira uma lista de escopos separados por espaço. Se você não inserir nenhum escopo, os padrões especificados no cliente OAuth serão usados.
  6. Insira um domínio permitido para a conexão. Não é possível alterar o domínio permitido depois de você criar a conexão. Para obter mais informações, consulte Domínio permitido.
  7. Clique em Salvar para criar a conexão.

Depois de criar a conexão, você pode visualizar os detalhes dela na página Conexões da Central de administração. Consulte Gerenciamento de conexões.

Observação: Ao criar uma conexão com um tipo de autenticação OAuth 2.0, os escopos incluídos na resposta do token de acesso do sistema externo são armazenados, não os escopos definidos ao criar a conexão. Esse valor não pode ser maior que 255 caracteres.

Domínio permitido

Cada conexão requer um nome de host da URL como um domínio permitido. A Zendesk só passa as credenciais da conexão em chamadas da API para esse nome de host. As tentativas de usar a conexão com outros nomes de host terão falha. Isso ajuda a evitar um vazamento acidental das credenciais da conexão. Depois de criar a conexão, você não pode alterar seu domínio permitido.

Por exemplo, você só pode usar uma conexão com um domínio permitido de "api.exemplo.com" para fazer chamadas da API ao nome de host “https://api.exemplo.com”.

Requisitos para domínio permitido

O domínio permitido de uma conexão não pode exceder 128 caracteres. Um subdomínio ou domínio no valor não pode exceder 63 caracteres. O valor deve conter um nome de domínio válido.

Uma conexão sempre usa um esquema https. Outros esquemas, como ftps, não são aceitos.

Curingas para domínio permitido

O domínio permitido de uma conexão aceita um subdomínio opcional com curinga (*). Isso permite que você use a conexão com o domínio simples e qualquer subdomínio. Por exemplo, você pode usar uma conexão com um domínio permitido de *.example.com para autenticar chamadas da API para “example.com” ou qualquer subdomínio de “example.com”.

Para usar um subdomínio com curinga, os primeiros dois caracteres do domínio permitido precisam ser *.. Não é possível usar um curinga em outras partes do nome do host. Por exemplo, você não pode usar um curinga dentro de um nome de host, como exam*.com ou my-*.example.com..

Você não pode usar um curinga com apenas um sufixo de domínio público, como *.com, *.com.au ou *.myshopify.com. Consulte a lista de sufixos públicos em publicsuffix.org.

Cabeçalhos HTTP para chaves da API

Quando você cria uma conexão com chave da API, é preciso especificar um nome de cabeçalho HTTP. Quando a conexão é usada para fazer uma chamada da API, o Zendesk passa a chave da API como o valor desse cabeçalho.

Muitas APIs usam um cabeçalho personalizado para aceitar chaves da API. Para obter o nome de cabeçalho apropriado para uma chamada da API, consulte a documentação correspondente.

Requisitos para nome de cabeçalho

O nome de cabeçalho de uma conexão de chave da API não pode exceder 128 caracteres. O nome do cabeçalho pode conter apenas letras, hifens (-) e sublinhados (_).

Você não pode usar os seguintes nomes de cabeçalho HTTP:
  • accept
  • accept-charset
  • accept-encoding
  • accept-language
  • cache-control
  • connection
  • content-md5
  • cookie
  • date
  • expect
  • from
  • host
  • if-match
  • if-modified-since
  • if-none-match
  • if-range
  • if-unmodified-since
  • max-forwards
  • pragma
  • proxy-authenticate
  • proxy-authorization
  • range
  • server
  • referer
  • te
  • trailer
  • transfer-encoding
  • upgrade
  • user-agent
  • via
  • warning
  • www-authenticate
  • Nomes de cabeçalho que começam com:
    • x-amz-
    • x-amzn-
    • x-forwarded-
    • x-zis-
Powered by Zendesk