Integrações

O modelo de segurança por trás da API externa: como as credenciais são guardadas, como a autorização é resolvida sem expor tokens internos, e o que limita o estrago de uma credencial vazada.

Duas credenciais, dois propósitos

Toda chamada à API externa combina duas credenciais com papéis diferentes, e essa separação é a base do modelo de segurança:

• A credencial de conta (gerada em Credenciais de API) prova quem está chamando. É a identidade do sistema integrador.
• A chave do processo (gerada no card do agente, ver Chaves de API) prova que aquele processo específico está liberado para esse consumidor.

Nenhuma chamada funciona com só uma das duas. Isso significa que vazar uma chave de processo sozinha não é suficiente para agir em nome de uma conta, e vazar uma credencial de conta sozinha não dá acesso a nenhum processo. É preciso as duas ao mesmo tempo, e cada uma pode ser revogada independentemente sem afetar a outra.

Como as credenciais são geradas

As duas credenciais nascem do mesmo princípio: um valor aleatório grande o bastante para ser inviável de adivinhar, produzido por um gerador de números aleatórios criptograficamente seguro, o mesmo tipo de mecanismo usado para gerar chaves de criptografia, não um gerador pseudoaleatório comum de propósito geral.

Nada nesse processo é derivado de datas, nomes, e-mails ou qualquer informação previsível, e duas credenciais geradas em sequência não têm relação matemática nenhuma entre si. Descobrir uma não ajuda a adivinhar a próxima, nem existe um padrão para "enumerar" credenciais válidas testando candidatos em sequência.

O prefixo da credencial de conta (a parte visível, ex.: bm_live_AbCd1234) não é secreto. Serve só para localizar rapidamente a qual conta uma credencial pertence, sem precisar testar o segredo contra todas as contas existentes. Quem efetivamente autentica é o segredo depois do ponto, e é essa parte que nunca é reexibida depois da criação.

Nada de segredo guardado em texto puro

A credencial de conta nunca é armazenada em sua forma original. No momento da criação, apenas uma impressão digital criptográfica (hash) dela é guardada. Mesmo com acesso total ao banco de dados, não é possível recuperar o segredo original a partir do que fica salvo. Só é possível confirmar se um valor apresentado bate com o hash guardado.

É por isso que o segredo completo só aparece uma única vez, no momento em que você gera a credencial: depois disso, nem a própria plataforma consegue mostrá-lo de novo.

A chave de processo, por sua natureza, ainda é reexibida por você mesmo no card do agente (é o modelo que permite renovar/copiar o código quando necessário). A proteção dela vem de outro lugar: só é aceita se o processo estiver com o acesso via API liberado, e pode ter validade e revogação configuradas (ver Chaves de API).

Autorização sem token de dono

Um detalhe importante de design: quando você chama a API sobre um processo que foi compartilhado com você (não é seu), você nunca precisa informar quem é o dono daquele processo. A plataforma resolve isso sozinha, na seguinte ordem:

1. Confere se o processo é seu.
2. Se não for, confere se ele foi compartilhado com a sua conta. E, se foi, o próprio registro do compartilhamento já indica quem é o dono real.
3. Só então valida se a chave apresentada pertence àquele processo, e se o compartilhamento inclui a permissão exigida pela ação (por exemplo, executar).

Isso elimina uma categoria de erro (e de risco) comum em integrações: nunca existe um campo "token do dono" para preencher errado, copiar de outro sistema ou vazar por engano. A identidade de quem possui o processo simplesmente não trafega pela chamada.

Expiração e revogação

Uma credencial expirada ou revogada passa a ser recusada imediatamente. Não existe carência nem cache de autorização entre chamadas. O mesmo vale para o interruptor de Permissão de Acesso das APIs do processo: desligá-lo bloqueia toda chave daquele processo na hora, mesmo as que continuam válidas.

Limites de uso e superfície de ataque

• Limite de requisições por credencial de conta, pensado para o volume normal de uma integração. Coíbe tentativas de adivinhar credenciais por força bruta e uso indevido em massa. Ver números atuais em Rotas de API.
• Limite mais apertado para disparo de execuções, já que esse é o efeito mais caro de uma chamada indevida.
• Chamadas entre navegador e servidor são restritas por origem (a mesma proteção de navegador que impede que uma página qualquer da internet chame a API em nome de uma sessão sua). O testador embutido na documentação é uma exceção deliberada, liberado apenas para uso local.

Rastreabilidade: quem fez o quê

Toda execução disparada via API carrega duas informações de identidade, com finalidades diferentes:

• A conta chamadora é quem recebe a atribuição de resultado na Trilha de Auditoria e nos Dashboards de ganho, inclusive em processos compartilhados, onde quem dispara (não o dono) é quem fica com a atribuição da execução.
• O identificador da chave de processo usada aparece como o nome do executor nos logs. É assim que dá para saber, dentre vários sistemas que usam chaves do mesmo processo, qual deles efetivamente disparou uma execução específica.

Isso significa que, ao investigar uma execução na Trilha de Auditoria, o identificador da chave é o dado mais direto para apontar qual integração a originou.

Isolamento da camada de integração

A API externa roda como uma camada própria, sem depender da sessão de navegador da interface web:

• Não usa cookies nem estado de login. Cada chamada se autentica sozinha pelas duas credenciais, o que também significa que não há risco de um ataque de falsificação de requisição entre sites (CSRF) contra ela.
• Uma sessão expirada, um logout ou uma troca de senha na interface web não têm nenhum efeito sobre credenciais de API. Elas são geridas e revogadas separadamente.
• A comunicação entre os serviços internos da plataforma que processam uma execução também exige um segredo compartilhado próprio, independente das credenciais do consumidor externo, ou seja, mesmo dentro da rede interna, um serviço não autorizado não consegue empurrar execuções.

Boas práticas

• Trate as duas credenciais como segredos de mesmo nível de sensibilidade. Nenhuma delas sozinha é segura de expor, mas ambas juntas dão acesso real. Guarde as duas em um gerenciador de segredos.
• Prefira várias credenciais pequenas a uma só compartilhada. Uma credencial de conta e uma chave de processo por sistema integrador, nunca reaproveite as mesmas credenciais entre integrações diferentes.
• Revogue no primeiro sinal de suspeita. Não espere confirmar um vazamento para agir. Revogar e gerar de novo é rápido e não tem custo de disponibilidade se feito em conjunto com a atualização do sistema consumidor.
• Use o interruptor de API do processo como kill switch quando quiser suspender todo o acesso externo a um processo sem mexer nas chaves individuais.
• Acompanhe a Trilha de Auditoria pelo identificador da chave para notar padrões de uso fora do esperado.