Boas Praticas de Seguranca

Principios fundamentais

1. Uma chave por integracao

Crie API keys separadas para cada sistema ou integracao:

Integracao	Chave	Permissoes
CRM	Integracao CRM	contacts.read, contacts.write, conversations.read
Chatbot	Chatbot Producao	messages.send, messages.read
Dashboard	Dashboard BI	conversations.read, contacts.read
Envio em massa	Campanhas Marketing	bulk-send.write, bulk-send.read, contacts.read

Vantagem: Se uma chave for comprometida, voce revoga apenas aquela chave sem afetar as outras integracoes.

2. Principio do menor privilegio

Conceda apenas os escopos estritamente necessarios para cada integracao:

# BOM: Apenas os escopos necessarios
{
  "permissions": ["messages.send", "messages.read"]
}

# RUIM: Todos os escopos (desnecessario e inseguro)
{
  "permissions": [
    "channels.read", "channels.write",
    "messages.send", "messages.read",
    "contacts.read", "contacts.write",
    "webhooks.read", "webhooks.write",
    "bulk-send.write", "bulk-send.read",
    "conversations.read", "conversations.write",
    "sandbox.write"
  ]
}

3. Nunca exponha chaves no frontend

API keys devem ser usadas exclusivamente em servidores backend:

CORRETO:
  Browser → Seu Backend → Ogmma API (com API key)

ERRADO:
  Browser → Ogmma API (com API key exposta no JavaScript)

Perigo

Chaves expostas em codigo client-side (JavaScript no navegador, apps mobile) podem ser facilmente extraidas e usadas indevidamente. Se uma chave for exposta, revogue-a imediatamente.

---

Rotacao de chaves

Rotacione suas API keys periodicamente para minimizar o risco de uso indevido:

Processo de rotacao

1. Crie uma nova chave com as mesmas permissoes
2. Atualize sua integracao para usar a nova chave
3. Teste se a integracao funciona com a nova chave
4. Revogue a chave antiga apos confirmar que tudo funciona

# 1. Criar nova chave
curl -X POST "https://oapi.ogmma.com.br/v1/api-keys" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Producao (rotacao fev/2025)",
    "permissions": ["contacts.read", "contacts.write"]
  }'

# 2. Apos atualizar a integracao, revogar a chave antiga
curl -X DELETE "https://oapi.ogmma.com.br/v1/api-keys/{oldKeyId}" \
  -H "Authorization: Bearer {JWT_TOKEN}"

Frequencia recomendada

Tipo de integracao	Frequencia
Integracoes criticas (pagamentos, dados sensiveis)	A cada 30 dias
Integracoes internas	A cada 90 dias
Integracoes de teste	Sem necessidade de rotacao

---

Armazenamento seguro

Variaveis de ambiente

Armazene API keys como variaveis de ambiente, nunca em codigo-fonte:

# .env (NUNCA commite este arquivo!)
OGMMA_API_KEY=oapi_sk_live_a1b2c3d4e5f6g7h8...

// Usar variavel de ambiente
const apiKey = process.env.OGMMA_API_KEY;

Gerenciadores de secrets

Para ambientes de producao, utilize gerenciadores de secrets:

• AWS Secrets Manager
• Google Secret Manager
• HashiCorp Vault
• Vercel / Railway Environment Variables

O que NAO fazer

• Nunca commite chaves em repositorios Git
• Nunca envie chaves por e-mail, Slack ou mensagens
• Nunca registre chaves em logs da aplicacao
• Nunca armazene chaves em banco de dados sem criptografia

---

Data de expiracao

Para chaves temporarias (ex: acesso a terceiros, testes), defina uma data de expiracao:

curl -X POST "https://oapi.ogmma.com.br/v1/api-keys" \
  -H "Authorization: Bearer {JWT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acesso temporario - Parceiro X",
    "permissions": ["messages.read", "conversations.read"],
    "expiresAt": "2025-03-01T00:00:00Z"
  }'

A chave sera automaticamente desativada na data configurada.

---

Monitoramento

• Revise periodicamente a lista de chaves ativas via GET /v1/api-keys
• Revogue chaves que nao estao mais em uso
• Investigue atividade incomum (volume de requisicoes fora do padrao)
• Configure alertas para falhas de autenticacao repetidas

---

Resposta a incidentes

Se voce suspeita que uma chave foi comprometida:

1. Revogue a chave imediatamente via DELETE /v1/api-keys/:id
2. Crie uma nova chave e atualize a integracao
3. Investigue o impacto: verifique logs de mensagens enviadas e operacoes realizadas
4. Notifique sua equipe sobre o incidente