Autenticação

Para autenticação na API, é utilizado o formato OAuth2 com chaves de API pré-compartilhadas. As chaves de acesso pré-compartilhadas são chamadas de Refresh Tokens, que são utilizados para gerar os Access Tokens. Os tokens de acesso são utilizados pelas APIs para autorização de acesso, bem como identificação do originador das requisições. Os Refresh Tokens são obtidos por meio de um cadastro de chaves de integradores na interface do sistema, que gera o token (chave do integrador) que deve ser enviado para o integrador.

Todos os Access Tokens tem um tempo limitado de uso, sendo necessário requisitar um novo token toda vez que o anterior expira. Para criar um novo token de acesso, deve ser realizada uma requisição para a URL /api/v1/oauth2/token, enviando o seu token de refresh pré-compartilhado:

POST /api/v1/oauth2/token HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json
Accept: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "asd2134asf.asdffsdfasd1234adsf.asdffaasd213asfd"
}

Dentro da resposta desta requisição será retornado o Access Token e os cookies. As chamadas de API podem ser feitas de duas formas: utilizando cabeçalho Authorization ou utilizando Cookies.

HTTP/1.1 200 OK
Set-Cookie: refresh-token=asd2134asf.asdffsdfasd1234adsf.asdffaasd213asfd; Path=/; HttpOnly; Secure; Max-Age=2592000
Set-Cookie: access-token=13asfda234adf.1234asf2314adf132.adsf134ssafa111; Path=/; HttpOnly; Secure; Max-Age=15
Content-Type: application/json

{
  "refresh_token": "asd2134asf.asdffsdfasd1234adsf.asdffaasd213asfd",
  "access_token": "13asfda234adf.1234asf2314adf132.adsf134ssafa111",
  "expires_in": 900
}

Autenticação utilizando cabeçalho Authorization

Depois de conseguir um Access Token, este deve ser utilizado dentro do cabeçalho Authorization, juntamente com o prefixo Bearer, para permitir o acesso as APIs. Segue um exemplo de uso do token de acesso em uma requisição:

GET /api/v1/users HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer 13asfda234adf.1234asf2314adf132.adsf134ssafa111

Caso o token de acesso tenha expirado, a API vai retornar o status 401 Unauthorized, conforme exemplo abaixo:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"msg": "Valid authentication token required"}

Autenticação utilizando Cookies

Na resposta da autenticação são setados dois cookies: o access-token e o refresh-token. Para acessar as APIs utilizando cookies é necessário passar os mesmos cookies para as requisições. Caso uma API seja acessada com o access-token expirado, o servidor fornece um novo token de acesso utilizando o refresh-token. O novo token de acesso deve ser armazenado e utilizado nas outras APIs. Exemplo de envio do cookie com o access-token expirado:

GET /api/v1/users HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json
Accept: application/json
Cookie: refresh-token=asd2134asf.asdffsdfasd1234adsf.asdffaasd213asfd

A resposta da API retorna o cookie access-token com o novo token de acesso, utilizado para acessar outras APIs.

HTTP/1.1 200 OK
Set-Cookie: access-token=13asfda234adf.1234asf2314adf132.GciOiJIUzI1NiJ9; Path=/; HttpOnly; Secure; Max-Age=15
Content-Type: application/json

{
  "total": 1,
  "users": [
    {
      "id": "Aoyc5feKgmFGhgESFupoL",
      "name": "João da Silva"
    }
  ]
}