Pular para o conteúdo principal

Autenticação

Para realizar a maioria das requisições no sistema, é necessário o usuário estar autenticado devidamente. Atualmente, o sistema disponibiliza duas formas de realizar autenticação: Por access token e por api-key

Autenticação por Access Token​

Este é o método original para acessar as funcionalidades do sistema. Se trata de realizar uma requisição para a rota /login e obter o accessToken (e opcionalmente o refreshToken). Em seguida, com as credenciais, é possível validar as requisições feitas para a API.

Obtendo as credenciais​

Primeiro é necessário realizar uma requisição do tipo POST para a seguinte URL:

POST /login
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "seuemail@email.com", "password": "Senha321@"}' \
  https://<endereço_da_api>/login

A resposta da requisição deve conter tanto os dados do usuário quanto as credenciais para usar nas requisições futuras:

Resposta do POST /auth/login
{
  "id": 1,
  "name": "Seu Nome",
  "email": "seuemail@email.com",
  "phone": "000000000000",
  "role": "supervisor",
  "accessToken": "eyJhbGc ....", // Seu token de acesso
  "refreshToken": "eyJhbGciO ...."
}

Autorizando as requisições​

Com o token de acesso em mãos, agora é possível realizar as requisições que necessitam de autenticação, basta adicionar no cabeçalho da requisição, utilizando o padrão Bearer Authentication:

GET /orders
curl -X GET \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer eyJhbGc ....' \ # Seu access token
  https://<endereço_da_api>/orders
Expiração do token

O token obtido é válido por um perídio limitado. Ao utilizar o token após esse período, uma mensagem de erro de autorização será retornada. Para continuar com suas requisições autorizadas, é necessário gerar outro token. Veja abaixo sobre o Refresh token

(Extra) Refresh token​

"Um token de atualização (refresh token) é um tipo especial de credencial de longa duração que permite a um cliente obter novos tokens de acesso (access tokens) sem que o usuário precise fazer login novamente".

Para obter um novo Access Token, utilizando o Refresh Token, é necessário fazer uma requisição utilizando o próprio refresh token como autenticação.

GET /auth/refresh
curl -X GET \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer eyJhbGc ....' \ # Seu refresh token
  https://<endereço_da_api>/auth/refresh

Note que o refresh-token antigo será invalidado. Um novo access token e refresh token serão enviados na resposta da requisição para uso.

Autenticação por Api-Key​

Uma outra forma de realizar autenticação é atráves da Api-key, uma forma mais definitiva e fixa de autenticação.

Como da forma anterior, basta enviar a autorização no cabeçalho da requisição.

Obtendo as credenciais​

A chave de API é uma chave única e fixa, que é enviada após ser solicitada à um administrador do sistema. Essa chave deve ser protegida e mantida em um local seguro, pois ela representa a sua identidade dentro do sistema. Ela é instransferível.

Perda de chave

Caso sua chave de API tenha sido perdida, contate imediatamente um administrador do sistema.

Autorizando as requisições​

A autorização por api-key é feita através do cabeçalho x-api-key da seguinte forma:

GET /orders
curl -X GET \
  -H "Content-Type: application/json" \
  -H 'x-api-key: Bearer eyJhbGc ....' \ # Seu access token
  https://<endereço_da_api>/orders