Autenticação e chaves

Toda chamada à API envia uma chave de API no cabeçalho Authorization:

http

Authorization: Bearer fst_...

A chave começa com fst_ e aparece uma única vez, na criação. O finstat guarda só o hash e não consegue recuperá-la. Quem cria e revoga chaves é o proprietário da empresa, no portal, em Chaves de API.

Escopos

Escopo	Nome no portal	Permite
`documents:write`	Enviar documentos	`POST /v1/documents`
`documents:read`	Consultar documentos	`GET /v1/documents/{id}`, `GET /v1/documents/{id}/result`, `GET /v1/history/{cnpj}`

Dê a cada sistema a própria chave, só com os escopos de que ele precisa. Um sistema que só lê resultados não precisa de documents:write.

Quando a chave é recusada

A API responde 401 unauthorized quando não há chave, quando ela é inválida, revogada ou expirada, quando não tem o escopo da rota e quando a empresa está suspensa. Não repita a requisição: confira a chave e os escopos.

Guardar a chave

Leia a chave de uma variável de ambiente ou de um gerenciador de segredos (FINSTAT_API_KEY).
Nunca coloque a chave no código, no Git, em logs ou no navegador. A API é para chamadas servidor a servidor.
Uma chave por sistema e por ambiente facilita revogar só o que vazou.

Trocar uma chave

Não há rotação automática nem rota de rotação. A troca é feita no portal, em Chaves de API, pelo proprietário; o portal pode pedir de novo a senha ou o código de autenticação.

Crie uma chave nova com os mesmos escopos (Nova chave). A empresa pode ter várias chaves ativas, então a antiga segue valendo durante a troca.
Troque FINSTAT_API_KEY no seu sistema e faça uma chamada de teste.
Confira o Último uso da chave nova na lista.
Revogue a antiga (Revogar, depois Confirmar revogação). A revogação vale a partir da próxima requisição: a chave antiga passa a receber 401.

Chave exposta

Revogue primeiro e crie a nova depois. Chave revogada não volta a valer. Se a chave tiver expiração, depois dela recebe 401.