Autenticação

Todos os endpoints disponibilizados pela API da Hash requerem autenticação para fim de validação das permissões de visualização e edição do usuário. Adicionalmente, todo usuário da API é associado a uma Company. Na descrição dos endpoints, quando houver referências à "company autenticada", isso se refere à company com a qual o usuário autenticado na requisição é associado.

A autenticação para o teste dos endpoints nesta documentação é realizada da seguinte forma:

  • O campo "username" deve ser preenchido com "jwt" ou "hash_key", de acordo com o tipo de chave de autenticação utilizada.
  • O campo "password" deve ser preenchido com a chave de autenticação.

Quando outros clientes HTTPS forem usados, a autenticação deve ser realizada pelo esquema HTTPS Basic, ou seja: Deve ser definido um header chamado Authorization na requisição, cujo valor deve ser a codificação em Base64 da concatenação do valor "username" conforme definido acima, seguido de um caractere dois-pointos (:), seguido da chave de autenticação.

Por exemplo:

Dada a "hash_key" hash_1234, o valor do header de autenticação na mensagem deve ser base64("hash_key:hash_1234"). O valor codificado dessa string é "aGFzaF9rZXk6aGFzaF8xMjM0". Assim, deve ser enviado o header Authorization: Basic aGFzaF9rZXk6aGFzaF8xMjM0 nas requisições realizadas via cliente HTTPS.

📘

"jwt" versus "hash_key": qual usar?

O JWT deve ser utilizado por humanos. Isto é, usuários que se autenticam com username e password. Esta forma de autenticação vincula o usuário ao seu contexto na company, trazendo então uma camada de permissionamento.

Já a hash_key deve ser utilizada por não-humanos. Ou seja, APIs e outros serviços devem utilizá-la, já que a hash_key não vincula um usuário ao seu contexto de autenticação; ela está vinculada estritamente à company que realiza a requisição.

Caso você deva utilizar a hash_key e ainda não tenha uma, entre em contato com a Hash para que fornecê-la de forma segura.

❗️

Atenção ao utilizar a hash_key

A hash_key é um chave estática e que permite realizar uma série de operações em nome do estabelecimento ao qual ela pertence. Assim, é de extrema importância que a mesma seja armazenada de forma segura, e que de maneira alguma ela seja exposta, por exemplo, em aplicações no frontend.

A hash_key ainda é uma forma válida de autenticação, mas não a retornamos mais nos nossos endpoints. Esta forma de autenticação deve ser descontinuada em breve.