Boas práticas de chave

A chave é a senha da sua integração. Quem tem a chave faz, pela API, tudo o que ela permite, em nome do membro que ela representa. Não há segundo fator e não há confirmação por e-mail. Cuidar da chave é cuidar da conta.

A chave aparece uma vez só

O servidor guarda apenas um hash SHA-256 da chave. Nem o suporte consegue ler uma chave já criada. Ela é mostrada na tela de confirmação da criação e não volta a aparecer.

O corpo da chave são 32 bytes sorteados pelo gerador criptográfico do sistema. Ninguém chega a uma chave por tentativa. O risco real é a chave vazar, e é contra isso que esta página serve.

Perdeu a chave: rotacione ou crie outra. Não existe recuperação.

Onde guardar

Guarde em cofre de segredo do seu provedor ou em variável de ambiente do servidor que faz as chamadas.

Nunca guarde a chave:

• No código. Nem em arquivo de configuração versionado, nem em constante “temporária”.
• Em repositório, mesmo privado. Quem clona leva a chave junto, e o histórico do git guarda o que você apagou depois.
• No navegador ou em aplicativo de celular. Qualquer pessoa que abra a página lê a chave. O CORS da API libera só as telas do próprio Faturei Hoje, então o navegador de outro site nem chega a ler a resposta.
• Em endereço. A API não lê chave em parâmetro de consulta. Endereço com chave dentro vaza em log de proxy, em histórico de navegador e no cabeçalho Referer.
• Em planilha, chat ou chamado de suporte. Nós nunca pedimos a chave.

A API aceita a chave em um lugar só, o cabeçalho Authorization no formato Bearer. Veja Autenticação.

Varredura de segredo

O formato da chave é fácil de procurar: fh_live_, 43 caracteres de corpo e 6 de verificação. Uma regra que case esse desenho acerta quase sempre.

Essa regra é você quem configura, na varredura de segredo do seu provedor de git ou na sua própria esteira. Nenhum provedor reconhece este formato sozinho.

Quando a inscrição no programa de varredura de segredo do GitHub estiver ativa, uma chave encontrada em repositório público do GitHub será revogada automaticamente, os endpoints de webhook cadastrados com ela serão pausados (motivo emergency_key_rotation, o mesmo da rotação “Parar agora”) e dono e administradores receberão um e-mail com o endereço onde ela apareceu. A inscrição ainda não está ativa: até lá, a regra acima continua sendo sua.

Uma chave por integração

Crie uma chave para cada sistema que integra, com um nome que diga qual é. Três motivos:

1. Revogar uma não derruba as outras. Quando uma chave vaza, você troca só ela.
2. O registro de uso fica legível. Com uma chave por sistema, o que aparece em Ver uso é o que aquele sistema fez, e não a soma de todo mundo.
3. A permissão fica do tamanho certo. Cada sistema recebe só o que ele usa.

Vale também para os seus ambientes. Não existe chave de teste nem ambiente de teste: o fh_test_ fica reservado e nunca é emitido. Se você tem produção e homologação, cada uma precisa da própria chave, senão desligar uma desliga as duas.

A menor permissão que resolve

Marque só o que a integração usa. O painel traz atalhos para começar: Somente leitura, Formulário de site e Acesso total.

A permissão não muda depois

Numa chave já criada dá para editar o nome e a lista de IPs, e nada mais. Trocar permissão exige uma chave nova, e a rotação copia as permissões da antiga. Marcar demais “por garantia” custa uma chave nova depois, e no meio do caminho custa acesso que ninguém precisava ter.

Dois limites que já vêm de fábrica:

• A chave nunca faz mais do que o membro que ela representa. A permissão efetiva é a interseção da permissão da chave com o papel e as permissões do membro, com o plano da empresa por cima. Está explicado em Permissões.
• Ninguém emite chave acima do próprio papel. Um ADMIN não cria chave que represente o OWNER.

Quando o membro é suspenso, removido ou tem o acesso desativado, a chave dele para de responder na hora, com 401. É o que faz “desligar a pessoa” desligar também as integrações dela.

Prazo de validade

Na criação você escolhe entre não expirar, 30 dias, 90 dias ou 1 ano. Depois da data a chave responde 401 como qualquer chave inválida, sem aviso prévio.

Prazo reduz a janela de estrago de uma chave esquecida. Se você escolher um, anote a data junto com o lembrete de trocar.

Rotacionar não renova prazo: a chave nova herda a data da antiga. Veja Rotação.

Acompanhe o uso

No menu da chave, em Ver uso, ficam as chamadas dos últimos 30 dias com data, método, rota, status, duração, IP e request_id. Chamada recusada também entra, desde que a API tenha reconhecido de qual chave se trata. O cartão da chave mostra ainda a data do último uso e quantos IPs estão na lista dela.

O que vale procurar ali:

• chamada vinda de um IP que não é seu;
• sequência de 401 que você não estava esperando;
• uso recente numa chave que você achava desligada;
• chamada em rota que aquela integração não deveria usar.

OWNER e ADMIN da empresa recebem e-mail quando uma chave é criada, alterada, rotacionada ou revogada. E-mail que ninguém da equipe esperava é sinal.

Se a chave vazou

Pare o vazamento antes de investigar

Descobrir como a chave vazou é importante. Parar o uso dela é urgente. Revogue primeiro e investigue depois: chave revogada não serve mais para ninguém.

1. Revogue agora. O efeito é imediato, não há desfazer e não há carência. Se você precisa da integração no ar, rotacione escolhendo Parar agora: isso gera a chave nova e mata a antiga na mesma ação.
2. Troque o segredo nos seus sistemas e confirme com uma chamada a GET /public/v1/me.
3. Leia o registro de uso dos últimos 30 dias procurando chamada que não foi sua. Guarde os request_id do que parecer estranho.
4. Tire a chave de onde ela vazou. Revogar não apaga a cópia que ficou no histórico do git, no log ou na conversa.
5. Se houve uso indevido, escreva para dev@fatureihoje.com com o que você encontrou. Veja Reportar uma falha.

Próximo passo

• IPs permitidos: quando a trava por endereço ajuda e quando ela derruba a integração.
• Rotação: trocar o segredo sem derrubar nada.
• Autenticação: o formato da chave e o roteiro do 401.