Chaves de API de IA com escopo do cliente: isole inquilinos, orçamentos e abusos sem expansão de chaves do fornecedor

Os campos exatos variam, mas o princípio não deveria: cada solicitação recebida resolve a chave na política do locatário antes do envio. A autenticação responde “quem está ligando?” A resolução de políticas responde “o que esse chamador pode fazer, quanto pode gastar, para onde a solicitação pode ser encaminhada e o que deve ser registrado?”

É aqui também que a estratégia semântica do produto é importante. Uma plataforma que vende uma API de IA para agências pode precisar de dimensões de cliente e de campanha. Uma ferramenta de desenvolvedor pode precisar de dimensões de espaço de trabalho e repositório. Um revendedor pode precisar de IDs de clientes externos que correspondam ao seu sistema de faturamento.

Fluxo de trabalho de criação de chaves

A criação de chaves deve ser determinística o suficiente para automação e rigorosa o suficiente para análise de segurança.

1. Crie primeiro o registro do cliente

Não crie chaves órfãs. A chave deve pertencer a um inquilino e a um registro de cliente antes de existir. Para plataformas de revendedores, o registro do cliente deve incluir IDs externos do CRM ou sistema de faturamento do revendedor, metadados do plano, agrupamento de impostos ou faturas, se necessário, e um campo de status que possa suspender todas as chaves filhas.

2. Anexe um perfil de modelo

Um perfil de modelo mapeia nomes de modelos voltados para o cliente para modelos e recursos de provedores. Por exemplo, support-standard pode permitir um modelo de texto balanceado, entrada de imagem e nenhuma execução de código. research-premium pode permitir modelos de contexto longo, pesquisa na web e limites mais altos por solicitação.

Não force aplicativos downstream a codificar IDs de modelo de provedor. Use o perfil do gateway para gerenciar disponibilidade, substituto, preços e suspensão de uso.

3. Definir limites de gastos e taxas

Use orçamentos e limites de taxas juntos. Um orçamento mensal evita danos às faturas ao longo do tempo. Os limites de taxa evitam que abusos repentinos, tempestades de novas tentativas ou loops acidentais consumam todo o orçamento em minutos.

Os controles úteis incluem:

• Orçamento mensal do cliente.
• Capacidade diária para detecção de anomalias.
• Taxa de solicitação por chave.
• Taxa de token de entrada e saída.
• Custo máximo estimado por solicitação.
• Limites específicos da ferramenta para pesquisa hospedada, processamento de arquivos ou execução de código.

A execução do orçamento deve reservar o custo estimado antes do envio, liquidar o custo real após a conclusão e liberar a reserva não utilizada. Isso conecta a política principal ao faturamento da AI API em vez de tratar o faturamento como uma tarefa de relatório atrasada.

4. Gere e armazene o segredo corretamente

Exibe o segredo em texto simples uma vez. Armazene apenas um hash forte, além de um prefixo curto ou impressão digital para pesquisa de suporte. O prefixo ajuda as equipes de suporte a identificar “a chave que termina em 8F2A” sem ver o segredo.

Um padrão de armazenamento típico é:

• key_id: identificador de banco de dados estável.
• secret_hash: hash do segredo completo usando uma senha apropriada ou estratégia de hash de token.
• secret_prefix: prefixo de exibição curto e não sensível.
• impressão digital: identificador determinístico para consulta de auditoria.
• created_by: usuário ou cliente da Partner API que criou a chave.
• status: ativo, drenando, revogado, em quarentena, expirado.

Nunca armazene chaves de provedor upstream no objeto de chave do cliente. As credenciais do provedor pertencem a um cofre de credenciais separado com regras de acesso próprias.

Aplicação no momento da solicitação

O gateway deve tratar cada chamada de modelo como uma decisão política seguida por um envio do provedor. Um caminho de solicitação prático é semelhante a este:

1. Analise a chave do gateway apresentada.
2. Procure o hash e o status da chave.
3. Resolver perfil de locatário, cliente, aplicativo, ambiente, proprietário e modelo.
4. Verifique se o locatário e o cliente estão ativos.
5. Valide o alias do modelo solicitado, modalidade, ferramentas, modo de retenção, região e nível de serviço.
6. Estime o custo da solicitação e reserve o orçamento.
7. Verifique os limites de taxas e limites de abuso.
8. Selecione o modo de credencial upstream: agrupado, vinculado ao locatário ou BYOK.
9. Enviar para o provedor.
10. Capture uso, custo, referências de fornecedores, erros e sinais de segurança.
11. Liquidar a reserva do orçamento e escrever o evento contábil final.

Essa sequência mantém o gateway responsável pelo contrato do cliente. Os painéis do provedor tornam-se entradas de reconciliação, não a única fonte de verdade.

Campos do razão de uso que realmente ajudam mais tarde

Um razão de gateway deve preservar detalhes suficientes para responder a perguntas de suporte, cobrança, abuso e roteamento sem exigir armazenamento bruto de prompts por padrão.

Os campos úteis incluem:

• request_id e trace_id.
• tenant_id, customer_id, application_id e key_id.
• Identificador do usuário final, de preferência pseudônimo quando apropriado.
• Alias do modelo solicitado pelo cliente.
• Provedor e modelo upstream resolvidos.
• Entrada, saída, raciocínio, cache, áudio, imagem, vídeo e uso de ferramentas quando aplicável.
• Custo cotado, valor reservado, custo liquidado, moeda e versão do catálogo de preços.
• ID da solicitação do provedor, referência do relatório de uso, projeto, espaço de trabalho ou dimensão de agrupamento de chaves de API, se disponível.
• Política de retenção aplicada.
• Códigos de segurança, abuso ou decisão política.
• Erro na categoria e tente novamente os metadados.

Essa estrutura oferece suporte a estorno, suporte ao cliente, resposta a incidentes e um fluxo de trabalho de gerenciamento de chaves de API que pode responder “o que essa chave fez?” sem expor inquilinos não relacionados.

Modos de credenciais: agrupados, vinculados ao locatário e BYOK

Credenciais de provedor agrupadas

No modo padrão, muitas chaves de cliente são roteadas por meio de um conjunto menor de credenciais de provedor. Isto é operacionalmente simples e reduz a expansão do lado do fornecedor. Funciona quando o gateway tem forte atribuição de locatário, aplicação de orçamento, limitação de taxa, isolamento de abuso e controles de limite de cache.

A desvantagem é que os relatórios do lado do provedor podem mostrar apenas a credencial do gateway ou o projeto do provedor. Você deve unir os registros do provedor aos registros contábeis do gateway para produzir faturamento e análises no nível do cliente.

Credenciais de provedor vinculadas ao locatário

Para locatários maiores ou mais arriscados, vincule um locatário a um projeto, espaço de trabalho, conta de serviço ou chave de provedor dedicado. Isto proporciona uma separação upstream mais forte e pode simplificar os relatórios do lado do fornecedor. Ele também pode fornecer uma barreira de cota rígida se o provedor oferecer suporte a limites nesse limite.

O custo é a complexidade operacional. O provisionamento, a rotação, os limites do provedor, a resposta a incidentes e a reconciliação agora acontecem em mais objetos upstream.

Traga sua própria chave

BYOK pode ser útil quando os clientes precisam possuir a conta do provedor, negociar seu próprio contrato de provedor ou manter a cobrança do provedor separada. O gateway ainda aplica perfis de modelo, política de roteamento, análises e controles em nível de aplicativo sempre que possível.

A desvantagem é a complexidade do suporte. A conta de provedor de cada cliente pode ter diferentes modelos de acesso, cotas, preços, configurações de retenção e status de incidente. O gateway deve detectar e explicar claramente essas diferenças.

Revogação e quarentena

A revogação deve bloquear imediatamente novas solicitações para uma chave de cliente, sem rotacionar credenciais de provedor upstream não relacionadas. Esta é uma das principais vantagens das chaves virtuais.

Use estados separados para diferentes ações operacionais:

• ativo: solicitações são permitidas.
• drenação: a chave antiga é aceita durante uma janela de rotação, mas avisos e eventos de auditoria são emitidos.
• revogado: novas solicitações são rejeitadas permanentemente.
• em quarentena: novas solicitações são bloqueadas devido a abuso, pagamento, política ou resposta a incidentes.
• expirou: a chave excedeu seu tempo de vida e deve ser substituída.

A quarentena deve ser reversível quando o incidente for resolvido. A revogação geralmente não deve ser reversível, porque restaurar segredos antigos aumenta a confusão e o risco.

Quando uma chave viola a política de uso, registre o motivo, o agente, a hora e o escopo da aplicação. Se a decisão foi automatizada, preserve a versão da regra e os sinais que a desencadearam. Isso mantém as conversas com os clientes factuais.

Rotação sem interrupção da produção

A rotação de chaves deve usar um fluxo de trabalho de sobreposição de duas chaves:

1. Crie uma chave substituta com o mesmo cliente, aplicação, perfil de modelo e limites, a menos que o operador os altere intencionalmente.
2. Exiba o novo segredo uma vez.
3. Marque a chave antiga como drenando.
4. Aceite ambas as chaves por um período limitado, como 7, 14 ou 30 dias, dependendo do plano e do risco do cliente.
5. Emitir avisos de uso na chave de drenagem.
6. Notifique o proprietário ou o cliente da Partner API quando a chave antiga ainda for usada perto do prazo.
7. Revogue a chave antiga no final da janela.
8. Mantenha a atribuição em ambos os IDs de chave no mesmo cliente e aplicativo.

Isso evita o modo de falha comum em que uma melhoria na segurança se transforma em uma interrupção na produção. O rodízio ainda é um controle, mas se torna um fluxo de trabalho operacional com evidências e prazos.

Superfície de API do parceiro

Se as plataformas downstream gerenciam os clientes de maneira programática, exponha as principais operações por meio de uma API de parceiro. A API deve oferecer suporte a chaves de idempotência e eventos de auditoria porque o provisionamento geralmente ocorre em fluxos de trabalho de faturamento, integração ou CRM.

Pontos de extremidade mínimos:

• POST /customers: cria ou atualiza um cliente.
• POST /customers/{customer_id}/keys: crie uma chave.
• GET /customers/{customer_id}/keys: lista chaves e status.
• PATCH /keys/{key_id}: atualiza escopos, proprietário, limites, perfil do modelo ou status.
• POST /keys/{key_id}/rotate: cria uma substituição e marca a chave antiga como drenada.
• POST /keys/{key_id}/revoke: revoga imediatamente.
• GET /customers/{customer_id}/usage: retorna uso e custo por intervalo de tempo, chave, aplicativo, modelo ou dimensão de usuário final.

Toda solicitação de mutação deve aceitar uma chave de idempotência. Cada mudança deve gravar um evento de auditoria com ator, destino, campos antes e depois, IP de origem ou identidade do cliente e motivo, quando disponível.

Quando usar projetos ou espaços de trabalho do provedor

Não trate as chaves do gateway e os limites do provedor como mutuamente exclusivos. Eles resolvem problemas diferentes.

Use chaves de gateway para controle normal no nível do cliente:

• Atribuição por cliente.
• Chaves por aplicativo.
• Limites de orçamento e taxa.
• Suspensão rápida.
• Fluxos de trabalho de rotação.
• Análise de uso e relatórios de revendedores.

Adicione projetos de provedores, espaços de trabalho ou credenciais de provedores dedicados quando o cliente precisar de uma separação mais forte:

• Alto volume mensal que merece cotas dedicadas.
• Cargas de trabalho regulamentadas com requisitos explícitos de residência ou retenção.
• Separação contratual da fatura.
• Orçamento rígido do fornecedor ou restrições de cota.
• Monitoramento dedicado de abusos ou limites de revisão de segurança.
• Contas de provedores de propriedade do cliente por meio de BYOK.

O padrão prático é o isolamento imposto pelo gateway com limites rígidos seletivos de upstream. Isso simplifica o caminho comum e preserva um caminho de escalonamento para clientes que precisam de mais separação.

Lista de verificação de implementação

• Defina um esquema de chave do cliente com inquilino, cliente, aplicativo, ambiente, proprietário, perfil do modelo, limites, política de retenção e status.
• Hash segredos em repouso e exibe texto simples apenas uma vez.
• Separe as chaves de gateway do armazenamento de credenciais do provedor upstream.
• Resolva todas as solicitações de acordo com a política antes do envio.
• Reserve o orçamento antes das ligações do provedor e liquide após o uso final ser conhecido.
• Registre o uso com cliente, chave, alias de modelo, modelo upstream, categorias de token, uso de ferramenta, custo cotado, custo liquidado e referências de fornecedor.
• Implemente estados ativos, de drenagem, revogados, em quarentena e expirados.
• Suporta sobreposição de rotação de duas teclas.
• Exponha as operações da Partner API com chaves de idempotência.
• Use projetos ou espaços de trabalho do fornecedor apenas quando o custo operacional for justificado.

Conclusão prática

O isolamento do cliente para acesso à IA geralmente deve começar na chave do gateway e não na chave do provedor. A chave do gateway é o contrato voltado para o cliente: ela nomeia o locatário, o cliente, o aplicativo, o perfil do modelo, o orçamento, o limite de taxa, a regra de retenção e a política de auditoria. A chave do provedor é um detalhe de implementação por trás desse contrato.

Essa arquitetura oferece aos construtores de SaaS e às plataformas de revenda revogação rápida, atribuição precisa, orçamentos por cliente, rotação controlada e análises de uso úteis sem criar um projeto de fornecedor upstream para cada cliente por padrão. Use projetos upstream, espaços de trabalho, credenciais vinculadas a locatários ou BYOK quando o risco, o volume, a residência ou o contrato exigirem. Para o caminho comum, aplique o isolamento do cliente no razão do gateway e no mecanismo de política e, em seguida, reconcilie os registros do provedor.

Leitura relacionada

• Provisionamento idempotente da API do parceiro para clientes, chaves e créditos