Obtenção do token de acesso OAuth para fins de teste

Se você está testando ou criando um aplicativo interno, talvez você não queira que suas solicitações de API sejam associadas a uma autenticação básica, que requer um nome de usuário e uma senha, ou à autenticação do token de API, que ainda requer um nome de usuário. A terceira opção é o uso do token de acesso OAuth.

Num primeiro momento, a criação de um token de OAuth, junto com seu fluxo de autorização elaborado, pode parecer uma tarefa desafiadora. No entanto, é possível ignorar as partes mais complicadas do processo e obter um token de acesso diretamente da API. Este artigo descreve como criar seu próprio token de OAuth para fins de teste em poucas etapas.

Dica: o modo mais rápido e fácil é criar um token diretamente no console da API em developer.zendesk.com. Para obter detalhes, consulte Criação rápida de token com o console da API.

Importante: a técnica descrita neste artigo consiste basicamente na troca de um nome de usuário e senha do Zendesk por um token de acesso. Como resultado, o token tem as mesmas vulnerabilidades de segurança de uma senha. Qualquer pessoa que tiver o token poderá acessar a conta. Guarde o token num local seguro e não faça uma codificação rígida dele no código do aplicativo. Em vez disso, armazene-o em uma variável de ambiente.

Criação do cliente de OAuth

A primeira etapa é criar um cliente de OAuth para fins de teste. Navegue até Admin. > API > Clientes de OAuth e clique no sinal de adição (+) no canto superior direito da lista. A configuração do cliente para fins de teste é um pouco diferente de a criação de um cliente de OAuth normal. Observe as diferenças a seguir:

O seu redirecionamento precisa ser uma URL HTTPS válida, mas não precisa ser um website real para esse projeto. Exemplo: https://algumsite.com.
O identificador exclusivo é o nome do seu cliente, usado no código. É possível obter a ID do cliente com o ponto de extremidade List Clients da API do cliente de OAuth.
Você talvez queira copiar seu segredo para referência futura. Depois de criado, ele não será exibido novamente, mas ele será necessário se você pretende usá-lo para criar um aplicativo da web OAuth ou para outros projetos.
Todos os outros campos podem ser preenchidos com dados fictícios.

Criação de um token de acesso

Agora você possui tudo de que precisa para criar um token com a API de tokens de OAuth. Demonstraremos como fazer a solicitação com cURL:

 curl https://{subdomain}.zendesk.com/api/v2/oauth/tokens.json \
   -H "Content-Type: application/json" \
   -d '{"token": {"client_id": "your_client_id", "scopes": ["read", "write"]}}' \
   -X POST -v -u {email_address}:{password}

É importante ressaltarmos algumas observações sobre este código:

Lembre-se de substituir o placeholder de subdomínio com seu próprio subdomínio
O valor de "client_id” é o número que você copiou da página Clientes de OAuth
Defina os escopos para ["read", "write"] a menos que você esteja testando em específico o acesso de somente leitura de um recurso

Execute a solicitação da cURL. Ela retorna um arquivo package.JSON composto por um objeto de token com diversas propriedades:

O valor de "full_token" corresponde ao seu token de acesso. Copie e guarde-o num local seguro!

Observe que a propriedade "expires_at" da resposta é "null", o que significa que o token somente irá parar de funcionar quando você apagar o próprio cliente. Na próxima vez que visitar Admin. > API > Clientes de OAuth, o número de tokens ativos para o seu novo cliente terá aumentado para 1.

Uso do seu novo token de acesso

Qual é a utilidade de se ter um token de acesso se você não tem em que usá-lo? Nenhum dos exemplos a seguir usa um nome de usuário ou senha. Esse é o padrão! Um token de acesso OAuth não depende de uma conta de usuário, essa é uma das vantagens para usar um token em seus aplicativos e scripts.

Uso de um token de acesso para a autenticação de uma solicitação de API

Qualquer chamada da API que requerer autenticação poderá ser feita com um token de acesso OAuth. Por exemplo, uma chamada para o ponto de extremidade dos tickets normalmente tem essa aparência:

curl https://{subdomain}.zendesk.com/api/v2/tickets.json \
   -u {email_address}:{password}

Com o token de acesso, tem essa:

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

Uso de um token de acesso num cliente de API

Você também pode usar um token de acesso OAuth em qualquer de nossos clientes de API. O cliente Ruby, por exemplo, normalmente requer autenticação com um nome de usuário e uma senha (ou token da API) como:

  config.username = "email do usuário"
  config.password = "senha do usuário"

Mostramos a seguir como fica a aparência se você usar o token de acesso:

 config.access_token = "seu token de acesso OAuth"