Chaves da API

Tudo o que se liga ao MoneyLights a partir de fora da aplicação — um script, uma integração, um assistente de IA — autentica-se com uma chave da API. Um tipo de credencial, um lugar para a gerir, um botão de revogação.

Criar uma chave

Vai a Definições → Chaves da API como um Proprietário ou Administrador da tua organização. Um Membro pode editar dados na aplicação, mas não pode emitir uma chave: uma chave atua sem supervisão, o que é um tipo diferente de responsabilidade.

Quando crias uma chave, escolhes:

Um nome — dá-lhe um nome baseado no sistema que a usará, não na pessoa.
Scopes — exatamente o que a chave pode fazer (vê abaixo).
Uma expiração — 30, 90, 180 ou 365 dias. Não há uma opção de “nunca expira” de propósito: uma credencial que ninguém pensa novamente é uma credencial que ninguém nota que foi exposta.
Uma lista de IPs permitidos (opcional) — restringe a chave à tua própria infraestrutura, para que uma chave exposta seja uma chave que funciona em mais lado nenhum.

O segredo (ml_sk_…) é mostrado uma vez, na criação. O MoneyLights armazena apenas um hash, então ninguém — incluindo o suporte — pode recuperá-lo mais tarde. Se o perderes, roda a chave.

Dá a cada integração a sua própria chave. Assim, podes cortar uma sem desligar as outras, e os números de utilização dizem-te qual sistema está a fazer o quê.

Scopes

Os scopes são pares recurso:ação — por exemplo transactions:read ou documents:write. Uma chave contém apenas os scopes que lhe concedeste, e:

Escrever implica ler, nunca o inverso. vendors:write também pode ler fornecedores; vendors:read nunca pode escrever.
Os scopes não podem ser editados após a criação. Precisar de um novo scope significa criar uma nova chave — alargar uma credencial no local seria uma alteração que ninguém vê.

O que uma chave pode realmente fazer é recalculado em cada pedido:

permissões efetivas = os scopes da chave ∩ o que o criador pode fazer agora ∩ o teu plano

Assim, se a pessoa que criou uma chave for rebaixada, a chave é restringida na próxima chamada. Se ela deixar a organização, as suas chaves param de funcionar imediatamente. Emite chaves sob uma conta que vai permanecer.

Rotação

Rotacionar emite um novo segredo para a mesma chave e permite-te escolher quanto tempo o antigo continua a funcionar: imediatamente, 24 horas ou 7 dias. A janela existe para que possas implementar o novo segredo sem tempo de inatividade. A chave mantém o seu nome, scopes, restrições de IP e expiração.

Rotaciona quando alguém com acesso ao segredo sai, quando pode ter sido exposto, e em qualquer cronograma que a tua própria política definir.

Avisos de expiração

O criador da chave é notificado 14, 7 e 1 dia antes de uma chave expirar, e uma vez que tenha expirado. Essas notificações não podem ser desligadas. Não esperes pelo último aviso: rotacionar a 14 dias custa uma implementação; descobrir uma chave expirada a zero custa uma interrupção.

Armazenar o segredo

Usa variáveis de ambiente ou um gestor de segredos — nunca controlo de versão, nunca um ficheiro de configuração que é enviado com a tua aplicação.
Nunca coloques a chave numa URL, numa linha de log ou num evento de análise. Pedidos que transportam uma chave na string de consulta são recusados imediatamente.
Nunca uses uma chave em código do lado do cliente. Uma chave num navegador ou numa aplicação móvel foi dada a todos que a utilizam.

Suspeitas de um vazamento? Revoga primeiro, investiga depois. A revogação está em Definições → Chaves da API, entra em vigor imediatamente, e está sempre disponível — mesmo que a tua subscrição esteja em atraso.

Próximos passos

Com uma chave na mão, podes chamar a API REST ou ligar um assistente de IA através do MCP — é a mesma credencial para ambos.