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 na etapa Fazer chamada de API do criador de bots ou para ações da assistência automática. Você precisa ser um administrador para criar conexões.
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
| 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 um bot, consulte Uso da etapa Fazer chamada de API no criador de bots. 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".
- 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.
Como criar um cliente OAuth
- Em Central de administração, clique em
Aplicativos e integrações na barra lateral e selecione Conexões > Conexões. - Insira um nome para o cliente. Não é possível alterar esse nome após criar o cliente.
- 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.
- 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.
- (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.
- Insira a URL do token. Essa é a URL usada para receber um token de acesso.
- 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.
- 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
- Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Conexões > Clientes OAuth.
- Clique em Criar conexão.
- Selecione um tipo de autenticação.
- Insira um nome para a conexão. Não é possível alterar esse nome depois de você criar a conexão.
- 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.
- 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.
- 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.
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 (_).
acceptaccept-charsetaccept-encodingaccept-languagecache-controlconnectioncontent-md5cookiedateexpectfromhostif-matchif-modified-sinceif-none-matchif-rangeif-unmodified-sincemax-forwardspragmaproxy-authenticateproxy-authorizationrangeserverreferertetrailertransfer-encodingupgradeuser-agentviawarningwww-authenticate- Nomes de cabeçalho que começam com:
x-amz-
x-amzn-x-forwarded-x-zis-