Chave Virtual do Gateway de IA (Virtual Key)
A Chave Virtual (Virtual Key) é uma credencial emitida pelo Gateway de IA para acessar os endpoints do proxy do gateway. Você distribui chaves virtuais para aplicativos e ferramentas de IA, enquanto a chave de API real do provedor fica armazenada apenas no lado do gateway. Isso evita que a chave real fique espalhada por aí e permite limitar permissões, restringir a taxa, rotacionar e revogar cada chave virtual individualmente. Este artigo apresenta o gerenciamento completo do ciclo de vida das chaves virtuais.
Por que usar Chaves Virtuais
- Proteja a chave real — Aplicativos e ferramentas entram em contato apenas com a chave virtual, e a chave real do provedor não vaza.
- Segmente permissões por finalidade — Crie chaves virtuais diferentes para cada projeto/ferramenta, restringindo individualmente os modelos disponíveis, os canais disponíveis e a taxa.
- Revogue a qualquer momento — Se uma chave for comprometida ou não for mais utilizada, basta revogá-la ou rotacioná-la sem afetar as outras chaves.
Pré-requisitos
- Estar conectado a uma conta ServBay.
- Ter adicionado ao menos um canal disponível na página de Canais.
Criar uma Chave Virtual
Acesse a página Gateway de IA → Chaves (Keys) e clique em Criar (Create):
- Nome — Usado para identificar a finalidade da chave (por exemplo,
claude-code,my-app-dev). - Descrição (opcional) — Informações complementares.
- Data de expiração — Pode ser definida como nunca expira ou uma data específica.
- Canais permitidos (opcional) — Selecione tags para limitar que a chave seja roteada apenas para canais específicos; deixe em branco para não restringir.
- Modelos permitidos (opcional) — Limite a chave para chamar apenas modelos específicos; deixe em branco para não restringir.
- Limite de taxa (opcional):
- RPM / TPM — Limite de requisições / tokens por minuto.
- RPD / TPD — Limite de requisições / tokens por dia.
Texto em claro pode ser recuperado a qualquer momento
Após a criação da chave, o gateway exibe o texto em claro da chave (no formato servbay-sk-xxxxxxxx...). O gateway armazena o texto em claro localmente, e ele ainda pode ser recuperado nos detalhes da chave depois; apenas chaves históricas criadas com hash em versões anteriores não têm texto em claro recuperável (retorna 409 ao tentar recuperá-lo). Se você suspeitar que a chave vazou, use diretamente a opção "Rotacionar".
Lista de Chaves
A lista de chaves exibe, para cada chave virtual:
- Prefixo — Como
servbay-sk-abcd..., usado para identificação. - Status — Ativa (active), revogada (revoked), expirada (expired).
- Data de criação / última utilização.
- Tags de permissão — Modelos/canais permitidos, limite de taxa.
Gerenciar Chaves
Na lista de chaves, é possível executar as seguintes operações em cada chave:
| Operação | Descrição | Impacto |
|---|---|---|
| Editar (Edit) | Modifica o nome, a descrição, os modelos/canais permitidos e o limite de taxa | Entra em vigor imediatamente, sem alterar a chave em si |
| Rotacionar (Renew) | Gera novamente o texto em claro, o antigo texto em claro é invalidado imediatamente, e o novo texto em claro pode ser recuperado a qualquer momento | É necessário atualizar todos os aplicativos e ferramentas que usam essa chave |
| Revogar (Revoke) | Desativa a chave imediatamente, mas mantém o registro de auditoria | Irreversível; as requisições com essa chave serão rejeitadas |
| Excluir (Delete) | Exclui a chave completamente | Irreversível |
Rotacionar vs Revogar
- Rotacionar (Renew): A chave continua existindo, apenas com um novo texto em claro — ideal para cenários em que você suspeita de vazamento da chave, mas ainda deseja usar a mesma configuração de chave; lembre-se de atualizar os consumidores.
- Revogar (Revoke): Torna a chave permanentemente inválida, mas mantém o registro, facilitando auditorias — ideal para cenários em que você confirma que a chave não é mais necessária. Tanto rotacionar quanto revogar exigem confirmação dupla.
Relação com a Adoção com Um Clique
Ao usar a Adoção com Um Clique para apontar uma ferramenta de IA para o gateway, o gateway cria automaticamente uma chave virtual dedicada para a ferramenta e a grava na configuração da ferramenta. Você também pode gerenciar manualmente essas chaves criadas automaticamente na página de chaves.
Perguntas Frequentes (FAQ)
- P: Esqueci de copiar o texto em claro da chave. O que fazer?
- R: Você pode recuperar o texto em claro nos detalhes da chave; apenas chaves históricas criadas com hash em versões anteriores não podem ser recuperadas, e nesse caso basta executar "Rotacionar".
- P: Qual é a diferença entre revogar e excluir?
- R: Revogar mantém o registro da chave (facilitando auditorias), enquanto excluir remove tudo definitivamente. Em ambos os casos, a chave se torna inválida imediatamente.
- P: Depois de restringir os "modelos permitidos", o que acontece quando o aplicativo solicita outros modelos?
- R: O gateway rejeitará requisições de modelos fora das permissões da chave. Certifique-se de que os modelos usados pelo aplicativo estejam na lista permitida, ou remova a restrição.
- P: O que acontece quando o limite de taxa é atingido?
- R: As requisições que excederem RPM/TPM/RPD/TPD serão limitadas pelo gateway. Você pode acompanhar o uso real na página de Estatísticas e ajustar os limites depois.
Resumo
As Chaves Virtuais permitem que você distribua recursos de IA para aplicativos e ferramentas de forma revogável e com privilégios mínimos. Combinadas com restrições de modelos/canais permitidos e limites de taxa, você pode criar credenciais sob medida para cada cenário de uso e rotacioná-las ou revogá-las a qualquer momento quando necessário, sem precisar tocar na chave de API real do provedor.
