Limitar o alcance de uma chave de API do MDC
Crie a chave já com escopo por endpoint, decida se ela pode escrever, defina expiração e saiba o que acontece ao revogar.
Etapa 1 de 4
Crie a chave com escopo
Nome do sistema e só os endpoints que ele usa.
-
No menu do MDC, em Conectar, abra Chaves de API. São as chaves do gateway do MDC, não a chave de API do Hub.
-
A janela Criar chave abre.
-
Use o nome do sistema que vai usar a chave, não algo genérico. É por ele que você vai reconhecê-la depois.
-
Em Escopo de Acesso, troque Todos os endpoints de banco por Endpoints específicos.
-
Em Endpoints de banco, busque por rota ou nome e marque só os que o sistema usa hoje.
Etapa 2 de 4
Defina a expiração e copie o token
Data de fim, sem escrita, e o token guardado na hora.
-
Em Expiração, troque Nunca expira por Data customizada. Para integração temporária, a data resolve o esquecimento.
-
Escolha o dia e a hora em que a chave deixa de valer.
-
Permitir escrita autoriza endpoints de escrita; uma integração que só lê não precisa disso. Deixe desligado e clique em Criar chave.
-
A janela Chave criada mostra o token uma única vez. Copie na hora e guarde em gerenciador de segredos: se perder, não há como recuperar.
-
A chave aparece na lista com o nome, o escopo e a expiração.
Etapa 3 de 4
Quem enxerga cada endpoint
O cartão Quem acessa responde de onde vem cada acesso.
-
Em Bancos de dados, abra a fonte do endpoint.
-
Na lista de endpoints da fonte, clique no endpoint.
-
Cada pessoa aparece com o caminho do acesso: acesso total ao app, administração da fonte, todos os endpoints, este endpoint ou só os metadados.
-
O cartão é de leitura. Para conceder ou tirar acesso, volte à fonte por Ver fonte e use Gerenciar acesso.
Etapa 4 de 4
Ativar, desativar e revogar
Suspenda, revogue e, se precisar, traga a chave de volta.
-
No menu de ações da linha, Desativar deixa a chave existir sem autenticar. É o passo reversível enquanto você apura um vazamento.
-
Revogar pede a confirmação Revogar e mover para a lixeira. A chave para de autenticar na hora.
-
Chaves revogadas ficam na Lixeira e podem ser restauradas por 30 dias.
-
Restaurar chave reabilita o mesmo token, que não é exibido de novo. A chave volta como inativa.
-
No menu da linha, Ativar faz a chave voltar a autenticar. Quem ainda tem o token volta a conseguir usar.
Precisa de mais? Abra um chamado dentro do Hub.
Ler este passo a passo em texto
Uma chave de API do MDC é o que permite a um sistema externo consumir os seus endpoints pelo gateway. Não é a chave de API do Hub: esta fica no app MDC, em Chaves de API, e serve aos endpoints publicados sobre os bancos conectados. 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.
- Um banco conectado com endpoints publicados. Sem banco, a lista de chaves mostra Conecte um banco primeiro, porque as chaves servem os endpoints dos bancos.
Crie a chave com escopo
- No menu do MDC, em Conectar, abra Chaves de API e clique em Nova chave. A janela Criar chave abre.
- 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.
- Escolha o Escopo de Acesso. As opções são Todos os endpoints de banco e Endpoints específicos.
- Se escolher específicos, selecione os endpoints. Em Endpoints de banco, o seletor busca por rota ou por nome e agrupa os endpoints por banco. Os escolhidos aparecem logo abaixo do campo, e dá para tirar um deles pelo x.
Defina a expiração e copie o token
- Defina a Expiração. Você pode deixar Nunca expira ou escolher Data customizada, com o dia e a hora. Para integração temporária, como uma migração ou um teste com fornecedor, a data resolve o esquecimento.
- Decida sobre a escrita. Permitir escrita autoriza a chave a executar endpoints classificados como escrita, os que alteram dados. Uma integração que só lê relatório não precisa disso: deixe desligado.
- Confirme em Criar chave e copie o token na hora. A janela Chave criada mostra o token uma única vez e avisa: guarde em gerenciador de segredos, porque se perder não há como recuperar. Feche a janela e a chave aparece na lista.
Na lista, cada chave mostra o nome, o Escopo (todos os endpoints de banco, ou quantos específicos), se é de leitura ou escrita, a Key (só o começo e o fim do identificador), o status, o último uso, o Limite (600 chamadas por minuto por chave) e as datas de expiração e de criação.
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.
Para chegar nele, abra a fonte em Bancos de dados e clique no endpoint. Esse cartão é de leitura. Conceder ou tirar acesso continua sendo feito no acesso da fonte, e não aqui: volte à fonte por Ver fonte e use Gerenciar acesso. Use-o quando a pergunta for “quem enxerga este dado”, que é a pergunta que costuma aparecer em auditoria.
Ativar, desativar e revogar
As três ações ficam no menu de ações da linha da chave (os três pontos, à direita), junto com Copiar identificador.
- Desativar deixa a chave existir sem autenticar. É o passo reversível quando você suspeita de vazamento e ainda está apurando. Ativar faz o caminho de volta.
- Revogar pede a confirmação Revogar e mover para a lixeira: a chave para de autenticar na hora e vai para a aba Lixeira. Chaves revogadas ficam lá e podem ser restauradas por 30 dias.
- Restaurar chave, no menu da linha da Lixeira, reabilita o mesmo token, e ele não é exibido de novo. Uma chave revogada desativada volta como inativa (Chave restaurada 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, na coluna Escopo, quantos endpoints específicos alcança (por exemplo, 2 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
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| A integração recebe recusa em um endpoint que deveria funcionar | O endpoint ficou fora do escopo da chave | Edite a chave e inclua o endpoint, ou mude para todos os endpoints de banco |
| A integração lê mas não consegue gravar | Permitir escrita está desligado | Ligue a opção apenas se a integração precisar mesmo escrever |
| Perdi o token | Ele é exibido uma única vez | Crie uma chave nova e desative a anterior. Não há como recuperar o token |
| Restaurei a chave e continua sem funcionar | Ela volta da lixeira como inativa | Ative a chave para que volte a autenticar |
| A chave parou de funcionar de uma hora para outra | Ela chegou na data de expiração | Crie uma nova, ou ajuste a expiração antes que a data chegue |
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.
Continue por aqui
Não resolveu?
Abra um chamado pelo botão de suporte dentro do Hub. Nosso time responde e, quando é problema de produto, ele vira uma correção rastreável.