BYOK e chaves de API

Voce traz sua propria chave do provedor de IA (OpenAI ou Anthropic) e nos cuidamos para usar apenas o estritamente necessario.

Por que BYOK e nao reselling

O UltronChat nao revende creditos de IA. Voce cadastra sua chave diretamente e paga o provider direto. Motivos:

• Transparencia de custo — voce ve cada chamada no dashboard do OpenAI/Anthropic. Sem intermediario, sem markup.
• Limites sob seu controle — voce define hard limit mensal na conta do provider.
• Sem lock-in — se amanha voce quer parar, basta revogar a chave.
• Compliance — o provider e seu fornecedor direto de IA, com seu DPA, seus termos.

Como armazenamos

1. Criptografia AES-256-GCM — igual aos tokens OAuth.
2. Chave derivada por HKDF — usando a TOKEN_ENCRYPTION_KEY como master.
3. Fingerprint de 4 caracteres — guardamos os 4 caracteres finais (ex.: sk-...a3f2) para voce reconhecer visualmente qual chave esta ativa. O resto fica so na forma cifrada.
4. Isolamento por usuario — RLS impede que voce veja chaves de outros usuarios, mesmo via API direta ao banco.

Probe de validacao

Sempre que voce cadastra ou testa uma chave, fazemos uma chamada real ao provider para validar:

• OpenAI — GET /v1/models. Responde 200 se a chave e valida; 401 se invalida.
• Anthropic — POST /v1/messages com modelo claude-haiku-4-5 e max_tokens = 1. Custo minimo (~US$ 0.0001), mas confirma que a chave funciona e tem saldo.

Se a chave falhar, nao gravamos. Se passar, gravamos e deixamos last_validated_at = now().

Quando a chave e usada

• Somente a Edge Function ai-responder decripta e usa sua chave, no momento exato de gerar uma resposta.
• Cada chamada e feita HTTPS direto para api.openai.com ou api.anthropic.com.
• Nao fazemos proxy intermediario, nao logamos prompts completos, nao guardamos respostas alem das mensagens que salvamos no historico de conversa (igual qualquer DM recebida).

Resolucao hibrida

Como explicado em BYOK chave global e chave por agente, a chave usada e escolhida em 2 niveis:

1. Especifica do agente (se cadastrada).
2. Global do usuario, senao.

Se nenhuma existe, o agente e bloqueado de ativar.

O que acontece se uma chave vazar

Se voce suspeita que sua chave foi exposta:

1. Va para /dashboard/settings/api-keys e clique em Remover na chave.
2. Va para o dashboard do provider e revogue a chave la tambem (em OpenAI ou Anthropic).
3. Gere uma nova chave no provider.
4. Cadastre a nova no UltronChat.

Ao remover a chave no UltronChat, agentes dependentes sao automaticamente pausados (trigger no banco) para evitar erros em serie.

Rotação

Boa pratica: rotacione a chave periodicamente (a cada 90-180 dias). O procedimento:

1. Gere nova chave no provider.
2. Cadastre a nova chave no UltronChat (vai substituir a antiga no modo global, ou voce cadastra como especifica e remove a global quando sentir seguro).
3. Revogue a chave antiga no provider.

Permissoes minimas

Recomendamos que a chave que voce usar no UltronChat tenha escopo apenas para os modelos que voce pretende usar:

• OpenAI — crie um project dedicado ao UltronChat. Na chave, limite /v1/chat/completions e /v1/audio/transcriptions.
• Anthropic — use workspace dedicado. Hoje o Anthropic nao tem escopo fino, mas voce pode definir limite de gasto mensal.

Proximo passo

LGPD e privacidade — como tratamos seus dados pessoais e os dados dos seus clientes.