Chave Virtual (Virtual Key) no AI Gateway
A Chave Virtual (Virtual Key) é uma credencial emitida pelo AI Gateway, usada para acessar os endpoints do gateway. Você entrega chaves virtuais para aplicações e ferramentas de IA, mantendo a chave real do fornecedor segura apenas no gateway. Assim, evita o vazamento da chave original, enquanto cada chave virtual pode receber permissões, limites e validade separados, podendo ser rotacionada ou revogada individualmente. Este artigo apresenta o gerenciamento completo do ciclo de vida das chaves virtuais.
Por que usar Chaves Virtuais
- Proteja a chave real — Aplicações e ferramentas acessam apenas a chave virtual, evitando a exposição da chave API original do fornecedor.
- Permissões segmentadas por uso — Crie diferentes chaves virtuais para projetos ou ferramentas distintos, controlando modelos, canais e limites de uso para cada uma.
- Revogação imediata — Em caso de vazamento ou desuso de uma chave, basta revogar ou rotacionar, sem interferir nas demais.
Pré-requisitos
- Estar logado em sua conta ServBay.
- Já ter adicionado pelo menos um canal disponível na página de canais.
Criando uma Chave Virtual
Acesse AI Gateway → Chaves (Keys) e clique em Criar (Create):
- Nome — Identifique claramente o propósito da chave (ex:
claude-code,my-app-dev). - Descrição (opcional) — Detalhes extras se necessário.
- Data de expiração — Pode ser configurada como "Nunca expira" ou uma data específica.
- Canais permitidos (opcional) — Selecione múltiplas opções para restringir a quais canais a chave pode rotear; deixe em branco para não limitar.
- Modelos permitidos (opcional) — Restringe o uso da chave a determinados modelos; deixe em branco para sem restrições.
- Limite de taxa (opcional):
- RPM / TPM — Máximo de requisições ou tokens por minuto.
- RPD / TPD — Máximo de requisições ou tokens por dia.
A chave em texto puro é exibida só uma vez
Após criar a chave, o gateway exibirá a chave em texto puro apenas uma vez (ex: servbay-sk-xxxxxxxx...). Copie e salve imediatamente. Depois de fechar, só o prefixo ficará disponível para identificação e não será possível visualizar a chave completa novamente. Caso perca a chave, será preciso rotacionar para gerar uma nova.
Lista de Chaves
A lista de chaves mostra para cada chave virtual:
- Prefixo — Ex:
servbay-sk-abcd..., para identificação. - Status — Ativa (active), Revogada (revoked), Expirada (expired).
- Data de criação / Último uso.
- Permissões — Modelos/canais permitidos, limites.
Gerenciando Chaves
Na lista de chaves, é possível realizar as seguintes operações para cada chave:
| Ação | Descrição | Impacto |
|---|---|---|
| Editar (Edit) | Altera nome, descrição, modelos/canais permitidos ou limites de uso | Efetivo imediatamente, mantendo a mesma chave |
| Rotacionar (Renew) | Gera uma nova chave em texto puro, a antiga é invalidada na hora | Atualize todas as aplicações que usam a chave |
| Revogar (Revoke) | Desativa imediatamente a chave, mantendo o registro para auditoria | Irreversível; requisições com essa chave serão recusadas |
| Excluir (Delete) | Remove a chave permanentemente | Irreversível |
Rotação vs Revogação
- Rotacionar (Renew): A chave continua existindo, mas um novo valor é gerado — ideal para casos de suspeita de vazamento onde ainda precisa usar a configuração original. Lembre-se de atualizar todos os sistemas que usam a chave.
- Revogar (Revoke): Torna a chave inválida permanentemente mas mantém o registro para auditoria — ideal quando a chave não será mais usada. Tanto a rotação quanto a revogação pedem confirmação adicional.
Relação com a Função de "Um Clique"
Ao usar o recurso Um Clique para apontar uma ferramenta de IA para o gateway, o gateway cria automaticamente uma chave virtual dedicada para essa ferramenta e já configura na aplicação. Você também pode gerenciar essas chaves manualmente na tela de chaves.
Perguntas Frequentes (FAQ)
- P: Esqueci de copiar a chave em texto puro. O que faço?
- R: Não há como recuperar a chave completa; faça a rotação para gerar um novo valor e substitua nas aplicações.
- P: Qual a diferença entre revogar e excluir uma chave?
- R: Revogar mantém o registro para auditoria; excluir apaga totalmente. Ambos tornam a chave inválida imediatamente.
- P: O que acontece se eu restringir os “modelos permitidos” e a aplicação pedir outro modelo?
- R: O gateway vai recusar requisições de modelos fora da lista. Garanta que os modelos usados estejam liberados ou amplie as permissões.
- P: O que ocorre quando o limite de taxa é atingido?
- R: Requisições acima dos limites RPM/TPM/RPD/TPD serão bloqueadas pelo gateway. Analise o uso na página de Estatísticas para ajustar os limites conforme necessário.
Resumo
Chaves virtuais permitem fornecer capacidades de IA a aplicações e ferramentas com permissão mínima e revogável. Com controles de modelos/canais e limites de taxa, você pode criar credenciais sob medida para cada cenário, e rotacionar ou revogar sempre que preciso — tudo sem expor a verdadeira API Key do fornecedor.
