Visão geral

Autenticação de sistemas externos

Visão geral

Após o cadastro do sistema externo, serão disponibilizados os dados ClientId e SecretKey. Essas credenciais são utilizadas tanto para a geração do Token JWT quanto em todas as requisições realizadas à API.

A API adota um modelo de autenticação em dois níveis, no qual o sistema externo é autenticado por meio do JWT, e o acesso à base de dados é definido por um mecanismo adicional de autorização: OAuth 2.0 ou API Key. Esses dois mecanismos são alternativos, sendo necessário informar apenas um deles por requisição.

Fluxo de autenticação

  1. O sistema externo utiliza o ClientId e a SecretKey para gerar um Token JWT
  2. O Token JWT identifica o sistema externo e possui validade determinada
  3. Em todas as requisições à API, devem ser enviados:
    • ClientId
    • SecretKey
    • Token JWT
    • OAuth 2.0 ou API Key, conforme o cliente/base a ser acessada

1. Geração do Token JWT

O Token JWT é gerado a partir das credenciais do sistema externo.

  • Headers utilizados:
    • X-Client-Id
    • X-Secret-Key
  • Validade do token: 24 horas

O JWT gerado deverá ser reutilizado até sua expiração.

2. Utilização do Token JWT nas requisições

O Token JWT é obrigatório em todas as requisições, independentemente da rota acessada.

  • Header:
    • Authorization: Bearer {token}

3. Credenciais obrigatórias em todas as requisições

Todas as chamadas à API devem conter os seguintes headers:

  • X-Client-Id
  • X-Secret-Key
  • Authorization: Bearer {token}

A ausência de qualquer uma dessas credenciais resultará na rejeição da requisição.

4. Autorização por cliente (OAuth 2.0 ou API Key)

Para rotas que acessam ou modificam dados de clientes específicos, é necessária uma autorização adicional para definir qual base de dados será consultada. Essa autorização deve ser feita utilizando apenas um dos mecanismos abaixo:

  • OAuth 2.0
    • Token de autorização do cliente
    • Header: X-OAuth-Token

ou

  • API Key do cliente
    • Header: X-API-Key

O sistema valida o ClientId, a SecretKey e o JWT, e em seguida utiliza o OAuth 2.0 ou a API Key para identificar o cliente e direcionar a requisição para a base correspondente.

Regras importantes

  • ClientId e SecretKey são obrigatórios em todas as requisições
  • O Token JWT é obrigatório em todas as requisições
  • OAuth 2.0 e API Key são alternativos (não devem ser utilizados simultaneamente)
  • Para rotas que exigem autorização por cliente, a ausência do OAuth 2.0 ou da API Key resultará na rejeição da requisição
  • Requisições com credenciais incompletas ou inválidas serão rejeitadas