Integração da chave do provedor BYOK para gateways AI API: verifique as credenciais do cliente antes de rotear o tráfego

Não trate a integração do BYOK como uma caixa de texto que aceita uma chave upstream API e ativa imediatamente o roteamento. Em um gateway de produção AI API, as credenciais fornecidas pelo cliente precisam de um fluxo de trabalho de plano de controle: coletar a ligação do provedor, colocar a chave em quarentena, executar sondagens específicas do provedor, criar uma matriz de capacidade e só então anexar a credencial à política de roteamento do locatário.

O problema do leitor é operacional: um cliente cola uma credencial OpenAI, Anthropic, Gemini ou Azure OpenAI que parece válida, mas a primeira solicitação real falha porque a chave pertence ao projeto errado, não tem acesso ao modelo, não pode chamar o endpoint escolhido, tem uma cota fraca ou não expõe os dados de uso necessários para cobrança e reconciliação. O gateway deve descobrir essas restrições antes que o tráfego do cliente dependa delas.

Projete a credencial BYOK como um objeto de plano de controle com estado

Uma credencial BYOK deve ser separada da chave emitida pelo gateway usada pelos aplicativos. Os aplicativos devem chamar o gateway com uma chave virtual estável, enquanto o gateway mapeia esse locatário, plano de produto, perfil de modelo e política para uma credencial upstream verificada. Essa separação mantém a integração do aplicativo estável quando o cliente alterna uma chave upstream, altera projetos de provedor ou perde um recurso de modelo específico.

No mínimo, modele a credencial upstream com estes estados:

• enviado: recebido pelo plano de controle, mas ainda não utilizável.
• em quarentena: armazenado no cofre e bloqueado do tráfego ativo enquanto as análises são executadas.
• verificado: permitido para recursos específicos que passaram na verificação.
• degradado: ainda utilizável para algum tráfego, mas um ou mais recursos, sinais de cota ou expectativas de relatórios de uso falharam.
• suspenso: bloqueado temporariamente após erros de autenticação, permissão, cota, faturamento ou política.
• rotação necessária: ainda conhecido pelo gateway, mas deve ser substituído antes que o uso da produção continue.
• revogado: removido do roteamento e não aceito mais como substituto.

Essa máquina de estado é importante para equipes que estão construindo um LLM multiprovedor API gateway, porque um único sinalizador de “chave válida” normalizado oculta o comportamento específico do provedor. O gateway precisa saber quais endpoints, modelos, regiões, modalidades e modos de relatório são seguros para cada locatário.

Colete os campos de vinculação do provedor antes de solicitar o segredo

O formulário de integração deve solicitar o contexto de roteamento não secreto antes ou junto com o segredo. Esse contexto evita investigações ambíguas e produz mensagens de erro melhores.

OpenAI

Colete a organização e o projeto pretendidos, os perfis de modelo solicitados e se a chave é uma chave de usuário ou uma chave de conta de serviço. Um verificador útil deve verificar a vinculação e as permissões do projeto porque OpenAI documenta o controle de acesso baseado em função nos níveis da organização e do projeto, e API permissões são governadas por esse modelo. Uma chamada como listagem de modelo pode exigir permissões de leitura de modelo da chave e função relevantes.

Para contas de serviço, trate os escopos como restrições, não como autoridade independente. OpenAI escopos de chave de conta de serviço podem limitar o que a conta de serviço pode fazer, mas não podem conceder permissões fora da função de projeto atribuída. Em termos práticos, uma chave pode parecer ter um escopo restrito e ainda assim falhar porque a função do projeto não permite o modelo ou endpoint solicitado.

Anthropic

Colete o ID do espaço de trabalho pretendido quando o cliente tiver mais de um espaço de trabalho ou usar fluxos vinculados à identidade. Anthropic espaços de trabalho podem conter membros, contas de serviço, API chaves e limites de recursos e destinam-se a separar projetos, ambientes ou equipes sob faturamento e administração centralizados.

O verificador deve preservar se uma solicitação precisava de um cabeçalho anthropic-workspace-id. Anthropic a documentação diz que fluxos de chave vinculados à identidade ou com vários espaços de trabalho API podem exigir esse cabeçalho. Evite também assumir que uma chave com âmbito de espaço de trabalho de tempo de execução pode inspecionar os limites de recursos ao nível da organização. As chaves com escopo no espaço de trabalho não são válidas para algumas operações de administrador API no nível da organização, como inspeção de limite de taxa do espaço de trabalho.

Gemini

Colete se a chave vem do AI Studio ou de um Google projeto do Cloud, o contexto do projeto pretendido, as APIs permitidas e quaisquer restrições que o cliente espera. A documentação da chave Gemini API de Google diz que cada chave Gemini API está associada a um projeto Google Cloud e novas chaves do AI Studio são criadas como chaves de autenticação. Ele também diz que chaves padrão irrestritas são rejeitadas pelo Gemini API como parte do abandono das chaves irrestritas inseguras.

A IU de integração deve sinalizar chaves padrão irrestritas e inseguras em vez de incentivar os clientes a relaxar as restrições até que a investigação seja aprovada. Google A orientação de API-chave da nuvem recomenda API restrições, evitando chaves em parâmetros de consulta, excluindo chaves desnecessárias e não confirmando chaves em repositórios. Gemini chaves de autenticação são uma exceção especial de produção porque Gemini API não cria Google recursos de projeto em nuvem, mas o verificador ainda deve registrar o tipo de chave e a postura de restrição.

AzureOpenAI

Colete o endpoint, o nome da implantação, API a versão, a região e o contexto da assinatura, se o cliente puder fornecê-los. O Azure OpenAI roteia por meio de implantações criadas pelo cliente, portanto, um nome de modelo genérico não é suficiente. Uma chave pode ser válida para o recurso enquanto o nome de implantação solicitado estiver ausente, em uma região diferente ou vinculado a uma versão de modelo que o gateway não espera.

Azure OpenAI é atribuída por assinatura, região, modelo e tipo de implantação em unidades TPM. Mapas TPM atribuídos aos limites de taxa de implantação, enquanto o RPM também é aplicado. As respostas em tempo de execução podem expor cabeçalhos de limite de taxa úteis, como solicitações restantes, tokens restantes e novas tentativas após ms. Capture esses sinais durante testes e monitoramento de tempo de execução.

Execute verificação em camadas

Um bom pacote de comprovação começa barato e de baixo risco, depois usa uma investigação mínima faturável somente quando o cliente consente. Alguns provedores não expõem introspecção suficiente por meio de chaves de tempo de execução, portanto, um resultado de integração bem-sucedido deve incluir um nível de confiança, e não apenas aprovação ou reprovação.

1. Verificações estáticas

Valide problemas óbvios de formatação, campos ausentes, formatos de endpoint incompatíveis, regiões sem suporte e nomes de implantação malformados antes de ligar para o provedor. As verificações estáticas nunca devem registrar o segredo bruto. Em vez disso, armazene uma impressão digital, uma fonte de criação, um ID de locatário, um provedor e uma referência de cofre.

Exemplos:

• O endpoint do Azure não corresponde ao padrão de URL do recurso esperado.
• O nome de implantação do Azure está vazio, embora o perfil do modelo solicitado seja mapeado para o Azure OpenAI.
• Anthropic ID do espaço de trabalho está faltando para um caminho de integração de vários espaços de trabalho.
• Gemini chave é marcada como chave padrão irrestrita quando restrições são necessárias.
• O perfil solicitado inclui geração de imagem, mas o adaptador do provedor não oferece suporte a essa modalidade para credenciais BYOK.

2. Sondagens de leitura de baixo risco

Use sondagens somente leitura onde o provedor permitir. Uma chamada de lista de modelos, uma verificação de metadados de implantação ou um endpoint de capacidade de conta podem revelar falhas de autenticação, vinculação de projeto e permissão sem gerar saída de modelo. Registre os resultados normalizados e os códigos de status brutos do provedor.

Os resultados normalizados recomendados incluem:

• auth_failed: credencial inválida, revogada, expirada ou desativada.
• wrong_project_or_workspace: chave válida, mas não vinculada ao projeto ou espaço de trabalho pretendido.
• permission_denied: endpoint, modelo ou permissão de administrador autenticado, mas ausente.
• model_unavailable: a chave funciona, o modelo solicitado ou a implantação não.
• quota_unknown: o tempo de execução funciona, mas a cota não pode ser inspecionada.
• usage_reporting_unavailable: o gateway não pode reconciliar o uso do lado do provedor por meio da credencial fornecida.

3. Testes de inferência mínima

Normalmente é necessária pelo menos uma sonda de inferência real para cada perfil de modelo solicitado, porque listar um modelo não é o mesmo que ter permissão para executá-lo. Peça o consentimento explícito do cliente, defina um pequeno orçamento de investigação e use o endpoint mais barato que exerça a capacidade necessária.

Mantenha as sondagens determinísticas e enfadonhas. Para um perfil de texto, envie um prompt curto com limite de saída baixo. Para streaming, verifique se o provedor retorna eventos de stream e metadados de uso final quando esperado. Para perfis compatíveis com ferramentas, use uma definição de ferramenta sintética e confirme se o provedor aceita o esquema da ferramenta. Para visão, use uma pequena imagem de teste conhecida se o provedor e a política permitirem. Evite investigações que armazenem dados confidenciais de clientes ou exijam solicitações específicas do negócio.

4. Testes negativos

Testes negativos provam que os limites das políticas são reais. Se um locatário só tiver permissão para usar um perfil de modelo definido, o verificador deverá tentar um modelo, endpoint, ferramenta ou região claramente não permitido e confirmar se o gateway o bloqueia antes que o provedor o veja. Esses são testes de política de gateway, não testes de abuso de provedor.

Isso é especialmente importante para configurações de revendedores e SaaS, onde AI API provisionamento de clientes cria chaves downstream automaticamente. Uma chave upstream fornecida pelo cliente não deve ignorar a política de gateway do locatário apenas porque tem permissões de provedor mais amplas.

Armazene uma matriz de capacidade, não um booleano

A saída da integração deve ser uma matriz de recursos anexada à versão da credencial. Essa matriz deve ser consultada por páginas de roteamento, suporte, faturamento e status voltadas para o cliente.

Uma matriz prática inclui:

• Provedor, versão da credencial, referência do cofre, locatário e ambiente.
• Organização observada, projeto, espaço de trabalho, endpoint, região ou vinculação de implantação, quando disponível.
• Endpoints suportados: bate-papo, respostas, mensagens, incorporações, lotes, tempo real, imagens, áudio ou equivalentes específicos do provedor.
• Modelos suportados e nomes de implantação.
• Recursos de solicitação suportados: streaming, ferramentas, modo JSON, saída estruturada, visão, áudio, cache de prompt, trabalhos em lote.
• Cabeçalhos de limite de taxa observados e cabeçalhos de nova tentativa.
• Fonte de cota conhecida: administrador API, cabeçalhos de tempo de execução, declarado pelo cliente ou desconhecido.
• Modo de relatório de uso: relatório do provedor disponível, medição somente de gateway, reconciliação parcial ou sem suporte.
• Confiança na verificação: profunda, superficial, somente em tempo de execução ou declarada pelo cliente.
• Última sondagem bem-sucedida, última sondagem com falha e evidência bruta de erro.

O roteamento deve consumir esta matriz. Se a matriz disser que a chave suporta inferência de texto, mas não trabalhos em lote, o gateway deverá permitir o tráfego de texto e rejeitar o tráfego em lote com uma mensagem clara voltada para o cliente. Se a cota não puder ser inspecionada, mas as sondagens de tempo de execução funcionarem, a credencial poderá ser marcada como verificada com confiança limitada, em vez de fingir que o gateway tem visibilidade de capacidade total.

Mapear os resultados da verificação na política de roteamento

O gateway não deve rotear diretamente do “provedor selecionado pelo locatário” para “usar este segredo”. Direcione da política de locatário para o perfil do modelo, do perfil do modelo para os requisitos de capacidade e dos requisitos para as versões de credenciais qualificadas.

Por exemplo:

tenant: acme-prod
virtual_key: mgk_live_...
model_profile: support-chat-standard
requirements:
  endpoint: chat
  provider_candidates: [openai, anthropic, azure_openai]
  features: [streaming, tools]
  max_region: customer_approved_regions
  usage_mode: gateway_metered_with_provider_reconciliation_preferred
eligible_credentials:
  - byok_openai_project_key_v3: verified, tools=true, streaming=true, usage_report=partial
  - byok_azure_openai_v2: degraded, deployment_found=true, quota_low=true
routing_decision:
  primary: byok_openai_project_key_v3
  fallback: none unless customer permits provider-managed spillover

Essa camada de política também protege a IA unificada API o faturamento. O BYOK pode enfraquecer o faturamento centralizado se o gateway simplesmente repassar as solicitações e confiar nas faturas do fornecedor posteriormente. Mesmo quando os relatórios de uso do lado do provedor não estão disponíveis, o gateway deve registrar o uso em nível de locatário, IDs de solicitação, perfil de modelo, contagens de token normalizadas quando disponíveis, confiança de reconciliação e qualquer modo de relatório não compatível.

Trate de falhas com uma linguagem voltada para o cliente

Os erros brutos do provedor são úteis para suporte, mas a maioria dos clientes precisa de orientação direta para correção. Armazene o código de erro bruto e os cabeçalhos internamente e, em seguida, converta a falha em uma mensagem estável.

Verifique novamente as credenciais após a integração

Uma simulação bem-sucedida é um instantâneo, não uma garantia. As funções do projeto, a política do espaço de trabalho, a cota, o estado de cobrança, a disponibilidade do modelo e a capacidade regional podem mudar após a integração. O gateway deve executar verificações de integridade programadas e novas verificações orientadas por eventos.

Acione uma nova verificação após:

• 401 ou falhas de autenticação do provedor.
• 403 ou respostas com permissão negada.
• Modelo 404, implantação ou respostas de endpoint não encontrado.
• 429, respostas com cota excedida ou limite de taxa fora dos padrões normais de tráfego.
• Erros de faturamento do provedor, organização, espaço de trabalho ou projeto.
• Alterações do cliente nos perfis de modelo, regiões, ferramentas ou política de dados solicitados.

Não suspenda imediatamente todo o locatário quando um recurso for interrompido. Se o streaming falhar, mas a inferência sem streaming ainda funcionar, marque a capacidade de streaming como degradada e encaminhe cargas de trabalho sem streaming elegíveis, se a política permitir. Se uma única implantação do Azure estiver faltando, bloqueie essa implantação em vez de todas as credenciais do provedor do cliente.

Crie a rotação como um fluxo de trabalho de verificação paralelo

A rotação não deve ser uma substituição cega. Crie uma nova versão de credencial, armazene-a em quarentena, execute as mesmas análises da integração original e alterne o roteamento atomicamente somente após a verificação ser aprovada. Mantenha a chave antiga em uma curta janela de reversão somente se o cliente permitir explicitamente e a política permitir o armazenamento contínuo.

Um fluxo de trabalho de rotação segura é assim:

1. O cliente envia credenciais de substituição e campos de vinculação.
2. O Gateway armazena o segredo como uma nova versão de credencial em quarentena.
3. O Verifier executa verificações estáticas, sondagens de leitura, sondagens de inferência e testes de política.
4. A matriz de capacidade é comparada com a versão ativa.
5. O cliente vê quaisquer regressões, como falta de suporte em lote ou menor confiança na cota.
6. O gateway muda o roteamento para a nova versão em uma atualização do plano de controle.
7. A versão antiga é revogada imediatamente ou mantida por uma janela de reversão curta e explícita.

A etapa de comparação é importante. Uma chave substituta que pode chamar o modelo de texto base ainda poderá ser uma regressão se perder o suporte da ferramenta, os relatórios de uso, a cota regional ou o acesso a uma implantação de produção.

Compensações a serem explicitadas

A verificação pode gerar pequenas cobranças ao provedor. A recomendação é pedir consentimento, mostrar um orçamento máximo de sondagem e usar solicitações e limites de saída mínimos. Não oculte sondagens faturáveis dentro da “validação”.

A introspecção do administrador melhora a confiança, mas aumenta o raio de alcance. Alguns clientes fornecerão credenciais de administrador ou de relatórios para uma verificação mais profunda. Outros fornecerão apenas chaves de tempo de execução. Apoie ambos, mas rotule claramente a confiança resultante.

A semântica do provedor não será normalizada corretamente. Uma única enumeração de status é útil para fluxos de produtos, mas as equipes de suporte precisam de códigos de provedor brutos, cabeçalhos, IDs de solicitação e evidências no nível do adaptador. Preserve registros normalizados e brutos.

BYOK altera a responsabilidade de cobrança. O BYOK oferece aos clientes controle do contrato do fornecedor, mas pode reduzir a capacidade do gateway de reconciliar faturas do fornecedor. O gateway deve expor se o faturamento é reconciliado pelo provedor, medido pelo gateway, parcial ou declarado pelo cliente.

A integração rigorosa retarda algumas configurações voltadas para vendas. Um modo sandbox limitado pode ajudar, mas deve ser claramente rotulado, limitado e bloqueado para promoção automática de produção. O roteamento de produção deve exigir capacidade verificada e mapeamento de políticas.

Lista de verificação de implementação

• Crie um objeto de credencial BYOK com estados de ciclo de vida explícitos e versões de credenciais imutáveis.
• Colete campos de vinculação específicos do provedor antes da verificação.
• Armazene segredos apenas no cofre de credenciais; registra impressões digitais e referências de cofre, não chaves brutas.
• Execute verificações estáticas antes das chamadas do provedor.
• Execute sondagens de leitura onde for permitido e preserve as evidências brutas do provedor.
• Execute uma sondagem de inferência mínima por perfil de modelo solicitado com o consentimento do cliente e um orçamento de sondagem.
• Execute testes negativos de política de gateway para modelos, ferramentas, endpoints e regiões não permitidos.
• Persista uma matriz de capacidade com nível de confiança, não um booleano.
• Roteie por meio de política de locatário e requisitos de perfil de modelo, não diretamente por meio de um segredo selecionado.
• Exponha mensagens de falha voltadas ao cliente com etapas de correção específicas.
• Programe verificações de integridade e acione novas verificações em caso de erros de tempo de execução.
• Implemente a rotação como verificação paralela seguida por um switch de roteamento atômico.

Conclusão

O fluxo de integração BYOK mais seguro é um verificador, não um formulário. Uma chave de provedor fornecida pelo cliente deve entrar em quarentena, comprovar sua vinculação, permissões, acesso de modelo, sinais de cota, comportamento de endpoint e limites de relatórios e, em seguida, tornar-se elegível apenas para os recursos aos quais ela realmente oferece suporte.

A recomendação prática é armazenar a verificação como uma matriz de capacidade, encaminhar através da política do locatário e continuar verificando novamente após o início do tráfego de produção. A previsão é direta: à medida que os tipos de chave do provedor, os controles do espaço de trabalho, as cotas regionais e as permissões específicas do modelo se tornam cada vez mais granulares, os gateways que tratam o BYOK como um upload secreto único verão mais falhas de produção evitáveis. Os gateways que fazem da verificação de credenciais parte do plano de controle integrarão os clientes mais lentamente no início, mas com menos surpresas após o início do tráfego.

Leitura relacionada

• padrão de armazenamento de credenciais para separar tempo de execução, administração, faturamento e acesso BYOK