External APIs - Chaves Globais

Resumo

Cofre central de credenciais globais da plataforma para serviços externos: provedores de IA (OpenAI, Anthropic, Gemini, Mistral, etc.), gateways de pagamento (global), OSINT, crawler (Firecrawl), e-mail transacional, storage remoto (S3/Vultr), SMS, push, WhatsApp, mapas, geolocalização, dados enriquecidos e demais APIs utilizadas por plugins e pelo core.

Para quem é (papel/role)

• super-admin - acesso exclusivo. Chaves globais não são visíveis a tenant-admin.

O que você pode fazer

Cadastro e gestão

• Adicionar credencial: provider, nome, chave/secret, ambiente (prod/sandbox).
• Editar: atualizar chave, rotacionar.
• Revogar: remove imediatamente do uso.
• Expiração: data opcional.
• Scopes: limitar o escopo de uso da chave.

Uso

• Dashboard de consumo: por provider, modelo, mês.
• Custo estimado.
• Limite por tenant: cota mensal de uso de IA/serviço pago.

Categorias suportadas

• IA: OpenAI, Anthropic, Google Gemini, Mistral, Cohere, Groq, Together, DeepSeek, entre outros.
• Gateways globais: quando a plataforma cobra diretamente.
• OSINT / enriquecimento: serviços de validação de dados.
• Crawler: Firecrawl, outros.
• E-mail transacional: Sendgrid, Mailgun, SES.
• Storage: AWS S3, Vultr Object Storage, Google Cloud Storage.
• SMS / WhatsApp: Twilio, Zenvia, providers WhatsApp oficiais.
• Push: FCM, APNs.
• Mapas / geo: Google Maps, Mapbox.
• Analytics: GA4, server-side.

Rotação e segurança

• Rotação agendada.
• Alerta de chave próxima do vencimento.
• Auditoria de uso.

Como acessar

1. /admin.
2. Settings → Integrações → External APIs ou /admin/settings/integrations/external-apis.
3. Também em /admin/settings/integrations/api-keys para chaves geradas pela plataforma.

Tutoriais

Adicionar chave OpenAI para uso global

1. /admin/settings/integrations/external-apis.
2. Clique em Adicionar e selecione OpenAI.
3. Cole a API key, ambiente: produção.
4. Defina cota mensal global e por tenant.
5. Salve. Plugins de IA passam a usar a chave.

Rotacionar chave do Stripe

1. Localize a credencial Stripe.
2. Clique em Rotacionar.
3. Cole a nova chave.
4. O sistema atualiza sem downtime; chave antiga fica em sunset por 24h.

Definir cota de IA para tenant específico

1. Na credencial de IA, aba Cotas.
2. Adicione o tenant e defina limite mensal.
3. Quando o tenant atinge, requisições são bloqueadas com erro claro.

Configurar Vultr Object Storage

1. Adicione credencial Vultr Storage.
2. Informe bucket, chave, secret, endpoint.
3. Teste upload pelo botão Testar.
4. Em platform-feature-flags.md, aponte o storage principal.

Integrações

• Billing - gateways também podem usar chaves daqui (billing-gateways.md).
• Integrações - credenciais por tenant em /admin/settings/integrations/accounts (integrations-apis-externas.md).
• Infraestrutura - backups e pipelines usam storage (infrastructure-servidor.md).
• AI Orchestration Layer - fallback entre provedores com estas chaves.

Perguntas frequentes

Tenant pode ter chave própria em vez de usar a global? Sim, em /admin/settings/integrations/accounts. A chave própria substitui a global para aquele tenant.

Chaves ficam criptografadas? Sim, em repouso e com mascaramento em logs.

Posso auditar quem usou uma chave? Sim, o dashboard de uso mostra por tenant/plugin/modelo.

O que acontece quando a cota é atingida? Requisições subsequentes retornam erro "quota exceeded" com mensagem clara.

Rotação derruba o sistema? Não. Janela de sunset garante continuidade.

Posso ter mais de uma chave do mesmo provider? Sim, para balanceamento ou por finalidade.

Chave de IA faz fallback entre providers? Sim, a camada de orquestração de IA tenta providers alternativos em falha.

Como evito custo descontrolado de IA? Cotas globais e por tenant, alertas de consumo e AiUsageBilling dedicado.

Limitações, políticas e avisos

• Chaves nunca aparecem em logs ou respostas de API.
• Apenas super-admin vê o valor real da chave; mascarado para demais.
• Revogar chave em uso interrompe plugins dependentes até substituir.
• Rate limit do provider pode ser atingido mesmo dentro da cota interna.

Relacionados

• integrations-external-apis.md
• billing-gateways.md
• infrastructure-server.md
• platform-feature-flags.md
• compliance-lgpd.md