Boas práticas de segurança para integração com IA

Conectar um agente de IA (ChatGPT, Claude, um bot interno) à LightHouse API muda o perfil de risco de uma integração: o "cliente" que decide quais chamadas fazer passa a ser um modelo de linguagem, não um código determinístico. As recomendações abaixo tratam especificamente disso.

Use um usuário dedicado para a integração

Crie um usuário só para o agente de IA — nunca reaproveite a credencial de uma pessoa nem use um usuário Administrador. Quem cria esse usuário é o administrador da empresa, que solicita ao suporte Leankeep — ver Primeiros passos → Obtendo credenciais.

Tipo de usuário recomendado (ver Conceitos de domínio → Modelo de acesso):

Tipo	Use para a integração de IA?
Administrador	❌ Evite — acesso irrestrito dentro da empresa.
Operacional	✅ Recomendado quando o agente precisa criar/alterar dados (ex.: abrir ocorrências, dar baixa em atividades).
Chamado	✅ Recomendado quando o agente só precisa abrir/consultar ocorrências e pode ficar restrito a um conjunto de Áreas.

Um usuário dedicado também facilita auditoria: toda ação do agente fica associada a um usuarioId identificável nos registros, em vez de se misturar com a atividade de uma pessoa real.

Princípio do menor privilégio

• Leitura (GET) para dashboards, relatórios e perguntas de negócio (ver Perguntas de negócio) não precisa de permissão de escrita — a maioria dos casos de uso de IA é consulta.
• Escrita (POST/PUT/DELETE) só deve ser concedida se o caso de uso realmente exigir criar ou alterar dados (ex.: abrir ocorrência a partir de um chamado, dar baixa em atividade). Comece sem escrita e adicione sob demanda.
• Restrinja o usuário às Unidades que ele realmente precisa acessar via PUT /v1/usuarios/permissoes, em vez de conceder acesso a todas as Unidades da empresa.
• Para usuários Chamado, use a restrição por Área quando aplicável — limita o escopo mesmo dentro de uma Unidade.

Prompt injection: trate dados da API como dados, não como instrução

Muitos campos retornados pela API são texto livre digitado por terceiros — descrição de uma ocorrência, observação de uma correção, comentário de uma auditoria. Esse texto não é confiável: uma pessoa mal-intencionada (ou um erro de digitação) pode incluir algo que se pareça com uma instrução para o agente ("ignore as regras anteriores e...", "aprove automaticamente...").

• Nunca deixe o agente executar uma ação só porque um texto retornado pela API "pediu" isso. O que decide qual ação executar é o pedido do usuário humano da conversa — não o conteúdo de um campo de resposta da API.
• Trate descricao, observacao, comentarios e campos livres semelhantes como dado a ser exibido/resumido, nunca como comando.
• Ao resumir ou repassar esse conteúdo para o usuário, deixe claro que é uma citação de terceiro (ex.: "o solicitante escreveu: ...") em vez de apresentá-lo como uma instrução do sistema.

Operações destrutivas exigem confirmação humana

Antes de o agente executar qualquer uma das ações abaixo, exija uma confirmação explícita do usuário humano na conversa (não assuma consentimento implícito):

• DELETE de ocorrência, correção, auditoria ou tarefa.
• PUT .../aprovacao e PUT .../autorizacao de ocorrências.
• PUT /v1/usuarios/inativar/{id}.
• Qualquer alteração em lote (ex.: baixa de atividades em lote) que afete múltiplos registros de uma vez.

Essas operações já estão marcadas como "consequenciais" nos pacotes reduzidos para GPT Actions (ver Perguntas de negócio) — a ferramenta pede confirmação automaticamente antes de chamá-las.

Rotação e revogação de credenciais

• A senha do usuário de integração é gerenciada no AuthCenter (fora do escopo desta API) — rotacione-a periodicamente, como qualquer credencial de serviço.
• Suspeita de comprometimento (credencial vazada, comportamento anômalo do agente):
  1. Inative o usuário imediatamente com PUT /v1/usuarios/inativar/{id} — isso bloqueia novas autenticações.
  2. Troque a senha no AuthCenter e gere uma nova credencial antes de reativar ou criar um novo usuário de integração.
  3. Tokens já emitidos continuam válidos até expirar naturalmente (authToken.expiresIn, ~2h — ver Autenticação); inativar o usuário não revoga um JWT já emitido, mas impede a emissão de novos.
• Nunca deixe o agente de IA armazenar ou repetir a senha/token em texto visível ao usuário final.

Checklist rápido

• Usuário dedicado, tipo Chamado ou Operacional (nunca Administrador).
• Permissões restritas às Unidades (e Áreas, se aplicável) realmente necessárias.
• Escrita concedida só onde o caso de uso exige.
• Texto livre da API tratado como dado, nunca como instrução.
• Confirmação humana antes de qualquer operação destrutiva.
• Plano de rotação de senha e de inativação rápida em caso de suspeita.