Limitar o alcance de uma chave de API

Uma chave de API é o que permite a um sistema externo consumir os seus endpoints pelo gateway. Ela não precisa ser tudo ou nada: dá para escolher quais endpoints ela alcança, se pode escrever e quando expira. Vale usar isso, porque uma chave larga vazada é um problema maior do que uma chave estreita vazada.

Antes de começar

• Acesso ao Marvee Data Connection com permissão para administrar chaves.
• Os endpoints que o sistema externo realmente precisa. A pergunta certa não é o que ele poderia usar, é o que ele usa hoje.
• Um gerenciador de segredos para guardar o token. Ele é exibido uma única vez.

Crie a chave com escopo

1. Abra Chaves de API e clique em Nova chave. A janela Criar chave abre.
2. Dê o Nome. É o identificativo da chave, e é por ele que você vai reconhecê-la depois. Use o nome do sistema que vai usar a chave, não algo genérico.
3. Escolha o Escopo de Acesso. As opções são Todos os endpoints de banco e Endpoints específicos.
4. Se escolher específicos, selecione os endpoints. O seletor busca por rota ou por nome, e tem Selecionar todos quando você quiser marcar o conjunto inteiro de uma vez.
5. Decida sobre a escrita. Permitir escrita autoriza a chave a executar endpoints de escrita, ou seja, POST, PUT, PATCH e DELETE. Uma integração que só lê relatório não precisa disso.
6. Defina a Expiração. Você pode deixar Nunca expira ou escolher Data customizada. Para integração temporária, como uma migração ou um teste com fornecedor, a data resolve o esquecimento.
7. Confirme em Criar chave e copie o token na hora. A tela mostra o token e avisa: guarde em gerenciador de segredos, porque se perder não há como recuperar.

Quem enxerga cada endpoint

Na tela de um endpoint existe o cartão Quem acessa, que responde de onde vem o acesso de cada pessoa. Ele mostra se a pessoa chega por ter acesso total ao app, por administrar a fonte, por ter acesso a todos os endpoints, por acesso direto àquele endpoint, ou só aos metadados.

Esse cartão é de leitura. Conceder ou tirar acesso continua sendo feito no acesso da fonte, e não aqui. Use-o quando a pergunta for “quem enxerga este dado”, que é a pergunta que costuma aparecer em auditoria.

Ativar, desativar e revogar

• Desativar deixa a chave existir sem autenticar. É o passo reversível quando você suspeita de vazamento e ainda está apurando.
• Revogar manda a chave para a lixeira. Chaves revogadas ficam lá e podem ser restauradas dentro do prazo de retenção.
• Restaurar reabilita o mesmo token, e ele não é exibido de novo. A chave volta como inativa, e é preciso ativá-la para que volte a autenticar. Pense nisso antes: quem ainda tiver o token volta a conseguir usar.

Como saber que deu certo

• A chave aparece na lista com o nome, o escopo e o status.
• Uma chave com escopo específico mostra que alcança endpoints específicos, e não todos.
• A chamada do sistema externo funciona nos endpoints escolhidos e é recusada nos demais.
• Ao desativar, a confirmação de chave desativada aparece e as chamadas passam a ser recusadas.

Problemas comuns

Próximo passo

• Chaves de API: conectar um sistema: o que a chave permite e como usá-la na chamada.
• MDC: como usar: fontes, endpoints e quem acessa o quê.
• MCP: como usar: quando a conexão é com um assistente, e não com um sistema.