Chaves de API
Como habilitar o acesso externo a um processo, gerar a chave do processo e a credencial da sua conta, e usar as duas juntas para disparar execuções, consultar progresso e agendar via API REST.
Para que servem
As Chaves de Acesso de API permitem que sistemas externos integrem com o browserMate sem passar pela interface web. Por exemplo:
- Um ERP dispara um processo de automação quando uma nota fiscal é recebida
- Um sistema de filas aciona execuções em lote com parâmetros diferentes
- Um painel externo consulta o progresso de execuções em andamento
- Um orquestrador ativa ou desativa o agendamento de processos
As chaves são configuradas por processo: cada processo tem seu próprio conjunto de chaves e seu próprio interruptor de liberação. Essa é uma das duas credenciais que uma chamada externa precisa: a outra é a credencial da sua conta, vista a seguir.
Credenciais de conta
Antes de entrar na chave de processo, vale conhecer a outra credencial: toda chamada à API também precisa provar quem está chamando, além de qual processo pode ser acessado. É para isso que existe a credencial de conta. Diferente da chave de processo (abaixo), ela não pertence a um processo específico: vale para qualquer processo que a sua conta tenha acesso, inclusive processos compartilhados com você.
- No painel Nova credencial, preencha um Label que identifique o sistema que vai usá-la (ex.:
ERP Produção) e, se quiser, uma Validade. Em branco, ela nunca expira. - Clique em Gerar credencial. O valor completo, no formato
bm_live_<prefixo>.<segredo>, aparece uma única vez. Copie e guarde em local seguro antes de sair da tela. - Use esse valor no header
Authorization: Bearer bm_live_...em toda chamada à API.
Ações disponíveis na lista
| Coluna / Ação | O que é |
|---|---|
| Label | O nome escolhido na criação, só para reconhecimento visual, não faz parte da autenticação. |
| Credencial | Mostra apenas o prefixo público (bm_live_<prefixo>); o segredo em si nunca volta a ser exibido depois da criação. |
| Criada / Expira / Último uso | Quando foi gerada, até quando vale (ou "Nunca") e a última vez que autenticou uma chamada. |
| Status | ATIVA, EXPIRADA (passou da validade) ou REVOGADA. |
| Revogar | Desativa a credencial imediatamente, mas mantém o registro na lista (histórico de criação e uso). Não existe "reativar": a saída é gerar uma nova. |
| Excluir | Remove o registro por completo da lista. Use depois de já ter revogado e não precisar mais nem do histórico. |
Gerenciar chaves de um processo
- No Menu, na opção Meus Agentes, localize o card do agente e clique no ícone ⇄ (APIs), na fileira de ícones abaixo dos botões RUN/EDIT/DEL.
- No modal Chaves de Acesso de API, preencha o campo Identificador, um nome para reconhecer quem usa a chave (ex.:
erp_producao,painel_bi) e rastrear, depois, qual chamada veio de qual chave. - Clique no botão Gerar Código (ícone de engrenagem). Uma chave aleatória forte é gerada para aquele identificador.
- Use + Adicionar chave para criar quantas chaves precisar, uma para cada consumidor, ambiente ou finalidade que você queira identificar separadamente.
- Clique em Salvar.
Renovar uma chave existente
O mesmo botão Gerar Código, clicado numa linha que já tem um identificador salvo, substitui o código daquele identificador por um novo. O identificador e seu histórico de uso continuam os mesmos, só o segredo muda. É a forma de renovar uma chave sem perder a identificação que já está configurada no sistema consumidor.
Liberar e bloquear o acesso
No topo do modal fica o interruptor Permissão de Acesso das APIs:
| Estado | Comportamento |
|---|---|
| 🔓 LIBERADO | As chaves cadastradas podem ser usadas para acessar o processo via API externa. |
| 🔒 BLOQUEADO | Todo acesso via API é negado, mesmo com chave válida. As chaves permanecem cadastradas para reativação futura. |
Como o sistema externo usa a chave
Cada chave cadastrada é a credencial de um sistema consumidor. O Identificador nomeia quem usa (e permite reconhecer a origem das chamadas), e o código gerado é o segredo apresentado pelo sistema externo ao integrar com o processo.
- Gere a chave e entregue o código ao responsável pelo sistema consumidor por um canal seguro (nunca por e-mail em texto puro).
- Confirme que a Permissão de Acesso das APIs do processo está em LIBERADO.
- No sistema consumidor, configure a chave conforme a operação desejada: disparo de execução, passagem de parâmetros, consulta de progresso ou agendamento.
Chaves em processos compartilhados
O gerenciamento de chaves de API é controlado pela permissão API do Compartilhamento:
- O dono do processo sempre pode gerenciar as chaves.
- Um usuário agraciado só vê o botão APIs se recebeu a permissão API ao ser compartilhado.
Boas práticas
- Uma chave por consumidor. Crie uma chave com identificador próprio para cada sistema que integra (ex.:
erp,bi,portal_cliente). Assim, revogar o acesso de um sistema não afeta os demais. - Guarde as chaves em local seguro. No sistema consumidor, armazene a chave em um gerenciador de segredos, nunca em código-fonte versionado.
- Rotacione periodicamente. Use Gerar Código no identificador para renovar a chave e atualize o sistema consumidor com o novo código. Veja Renovar uma chave existente.
- Bloqueie quando não usar. Se o processo não precisa de acesso externo no momento, mantenha o interruptor em BLOQUEADO.
- Remova chaves órfãs. Ao desativar uma integração, exclua a chave correspondente (ícone de lixeira) em vez de deixá-la ativa.