Autenticação

Rascunho. O modelo de credencial aguarda a decisão D6 em
interno/plano-de-organizacao.md. O fluxo abaixo descreve a proposta.

A API 77Sol usa credencial de máquina. Você troca sua credencial por um token de curta duração
e envia esse token em cada chamada.

Suas credenciais

Você recebe dois valores da 77Sol:

Valor	O que é
`api_key`	Identifica sua integração. Pode aparecer em log.
`secret`	Prova que a integração é sua. Nunca exponha.

Guarde o secret num gerenciador de segredo. Não coloque em repositório, em variável de front,
em app móvel nem em coleção compartilhada.

Cada credencial vale para um ambiente. A credencial de sandbox não funciona em produção.

Obter o token

Resposta:

{
  "access_token": "<token-jwt>",
  "token_type": "Bearer",
  "expires_in": 43200
}

O expires_in vem em segundos. São cerca de 12 horas.

Você não precisa saber nada sobre o provedor de identidade

A 77Sol usa um provedor de identidade por baixo, e o token que você recebe é emitido por ele.
Mas a única porta é a rota acima. Ela cuida de tudo: monta o pedido correto, aplica os
seus papéis e devolve o token pronto.

Não tente pedir token direto no provedor. Aquele caminho exige montar parâmetros que, se
vierem errados, produzem um token válido e sem permissão — sua integração recebe 401 em
toda chamada e o token não parece errado. É exatamente o problema que esta rota existe para
eliminar.

Se algum dia a 77Sol trocar de provedor, esta rota não muda e a sua integração não quebra.

Quando o token não funciona

Recebeu o token com sucesso e ainda assim toda chamada volta 401? Isso não é problema da
sua credencial. Abra chamado em tecnologia@77sol.com.br informando a sua api_key e o horário
— é configuração do nosso lado.

401 na própria rota de token é outra coisa: aí a credencial está errada, inativa, ou o
seu IP está fora da lista. A resposta é a mesma para os três casos, de propósito.

Usar o token

Envie o token no header Authorization, com o prefixo Bearer:

Regras do token

Reaproveite o token até ele expirar. Ele vale cerca de 12 horas. Não peça token novo em
cada chamada: o pedido de token conta no seu limite de uso.

Renove antes de expirar. Guarde o instante da emissão e renove com folga de um minuto.

Trate 401 renovando uma vez. Se o token novo também receber 401, pare. A credencial
está errada ou inativa.

Uma credencial por integração. Não compartilhe credencial entre sistemas: você perde a
capacidade de revogar um sem derrubar o outro.

Restrição por IP

A 77Sol pode amarrar sua credencial a uma lista de IPs de origem. Informe seus IPs de saída
quando pedir a credencial. Se o seu IP mudar, avise antes.

Se o secret vazar

Avise a 77Sol imediatamente. A revogação é imediata e derruba sua integração até você receber
a credencial nova. Um secret vazado sem aviso é pior do que uma integração parada.

Suas credenciais#

Obter o token#

Você não precisa saber nada sobre o provedor de identidade#

Quando o token não funciona#

Usar o token#

Regras do token#

Restrição por IP#

Se o secret vazar#