Intégration de la clé du fournisseur BYOK pour les passerelles AI API : vérifiez les informations d'identification du client avant d'acheminer le trafic

Ne considérez pas l'intégration BYOK comme une zone de texte qui accepte une clé API en amont et active immédiatement le routage. Dans une passerelle AI API de production, les informations d'identification fournies par le client nécessitent un workflow de plan de contrôle : collectez la liaison du fournisseur, mettez la clé en quarantaine, exécutez des sondes spécifiques au fournisseur, créez une matrice de capacités, puis attachez ensuite les informations d'identification à la stratégie de routage du locataire.

Le problème du lecteur est opérationnel : un client colle un identifiant OpenAI, Anthropic, Gemini ou Azure OpenAI qui semble valide, mais la première vraie requête échoue car la clé appartient au mauvais projet, n'a pas d'accès au modèle, ne peut pas appeler le point de terminaison choisi, a un quota faible ou n'expose pas les données d'utilisation nécessaires à la facturation et au rapprochement. La passerelle doit découvrir ces contraintes avant que le trafic client n'en dépende.

Concevoir les identifiants BYOK en tant qu'objet de plan de contrôle avec état

Un identifiant BYOK doit être distinct de la clé émise par la passerelle et utilisée par les applications. Les applications doivent appeler la passerelle avec une clé virtuelle stable, tandis que la passerelle mappe ce locataire, ce plan de produit, ce profil de modèle et cette stratégie à un identifiant en amont vérifié. Cette séparation maintient l'intégration des applications stable lorsque le client effectue une rotation d'une clé en amont, change de projet de fournisseur ou perd une fonctionnalité de modèle spécifique.

Au minimum, modélisez les informations d'identification en amont avec ces états :

• soumis : reçu par le plan de contrôle mais pas encore utilisable.
• mis en quarantaine : stocké dans le coffre-fort et bloqué du trafic en direct pendant l'exécution des sondes.
• vérifié : autorisé pour les fonctionnalités spécifiques qui ont réussi la vérification.
• dégradé : toujours utilisable pour une partie du trafic, mais une ou plusieurs fonctionnalités, signaux de quota ou attentes en matière de rapports d'utilisation ont échoué.
• suspendu : bloqué temporairement après des erreurs d'authentification, d'autorisation, de quota, de facturation ou de stratégie.
• rotation requise : toujours connu de la passerelle, mais doit être remplacé avant de continuer l'utilisation en production.
• révoqué : supprimé du routage et n'est plus accepté comme solution de secours.

Cette machine à états est importante pour les équipes qui construisent une passerelle LLM multi-fournisseurs APIpasserelle, car un seul indicateur normalisé de « clé valide » masque le comportement spécifique au fournisseur. La passerelle doit savoir quels points de terminaison, modèles, régions, modalités et modes de reporting sont sécurisés pour chaque locataire.

Collectez les champs de liaison du fournisseur avant de demander le secret

Le formulaire d'intégration doit demander un contexte de routage non secret avant ou à côté du secret. Ce contexte évite les sondes ambiguës et produit de meilleurs messages d'erreur.

OpenAI

Collectez l'organisation et le projet prévus, les profils de modèle demandés et indiquez si la clé est une clé utilisateur ou une clé de compte de service. Un vérificateur utile devrait vérifier la liaison et les autorisations du projet, car OpenAI documente le contrôle d'accès basé sur les rôles au niveau de l'organisation et du projet, et API les autorisations sont régies par ce modèle. Un appel tel qu'une liste de modèles peut nécessiter des autorisations de lecture de modèle à partir de la clé et du rôle appropriés.

Pour les comptes de service, traitez les champs d'application comme des restrictions et non comme une autorité indépendante. OpenAI étendues de clé du compte de service peuvent limiter les actions du compte de service, mais elles ne peuvent pas accorder d'autorisations en dehors du rôle de projet attribué. En termes pratiques, une clé peut paraître limitée et échouer car le rôle du projet n'autorise pas le modèle ou le point de terminaison demandé.

Anthropic

Collectez l'ID d'espace de travail prévu lorsque le client dispose de plusieurs espaces de travail ou utilise des flux liés à l'identité. Anthropic espaces de travail peuvent contenir des membres, des comptes de service, API clés et des limites de ressources, et ils sont destinés à séparer les projets, les environnements ou les équipes sous une facturation et une administration centralisées.

Le vérificateur doit conserver si une requête nécessite un en-tête anthropic-workspace-id. Anthropic la documentation indique que les flux de clés liés à l'identité ou multi-espaces de travail API peuvent nécessiter cet en-tête. Évitez également de supposer qu’une clé étendue à l’espace de travail d’exécution peut inspecter les limites de ressources au niveau de l’organisation. Les clés au niveau de l'espace de travail ne sont pas valides pour certaines opérations de l'administrateur API au niveau de l'organisation, telles que l'inspection des limites de débit de l'espace de travail.

Gemini

Déterminez si la clé provient d'AI Studio ou d'un Google projet Cloud, le contexte du projet prévu, les API autorisées et les restrictions attendues par le client. La documentation des clés Gemini API de Google indique que chaque clé Gemini API est associée à un projet Cloud Google et que de nouvelles clés AI Studio sont créées en tant que clés d'authentification. Il indique également que les clés standard sans restriction sont rejetées par le Gemini API dans le cadre de l'abandon des clés non restreintes et dangereuses.

L'interface utilisateur d'intégration devrait signaler les clés standard non restreintes et dangereuses au lieu d'encourager les clients à assouplir les restrictions jusqu'à ce que la sonde réussisse. Google Cloud API-key guidance recommande API des restrictions, en évitant les clés dans les paramètres de requête, en supprimant les clés inutiles et en ne validant pas les clés dans des référentiels. Gemini les clés d'authentification constituent une exception de production spéciale car Gemini API ne crée pas de Google ressources de projet Cloud, mais le vérificateur doit quand même enregistrer le type de clé et l'état de restriction.

Azure OpenAI

Collectez le point de terminaison, le nom du déploiement, API la version, la région et le contexte d'abonnement si le client peut le fournir. Azure OpenAI achemine via les déploiements créés par le client, un nom de modèle générique ne suffit donc pas. Une clé peut être valide pour la ressource alors que le nom de déploiement demandé est manquant, dans une région différente ou lié à une version de modèle que la passerelle n'attend pas.

Azure OpenAI est attribué par abonnement, région, modèle et type de déploiement en unités TPM. Le TPM attribué correspond aux limites de taux de déploiement, tandis que le RPM est également appliqué. Les réponses d'exécution peuvent exposer des en-têtes de limite de débit utiles tels que les requêtes restantes, les jetons restants et les nouvelles tentatives après ms. Capturez ces signaux pendant les sondes et la surveillance de l'exécution.

Exécuter la vérification en couches

Une bonne suite de contrôle en amont commence à moindre coût et à faible risque, puis utilise une enquête facturable minimale uniquement lorsque le client a consenti. Certains fournisseurs n'exposent pas suffisamment d'introspection via les clés d'exécution. Un résultat d'intégration réussi doit donc inclure un niveau de confiance, et pas seulement une réussite ou un échec.

1. Vérifications statiques

Validez les problèmes de formatage évidents, les champs manquants, les formes de point de terminaison incompatibles, les régions non prises en charge et les noms de déploiement mal formés avant d'appeler le fournisseur. Les vérifications statiques ne doivent jamais enregistrer le secret brut. Stockez plutôt une empreinte digitale, une source de création, un ID de locataire, un fournisseur et une référence de coffre-fort.

Exemples :

• Le point de terminaison Azure ne correspond pas au modèle d'URL de ressource attendu.
• Le nom du déploiement Azure est vide même si le profil de modèle demandé est mappé à Azure OpenAI.
• Anthropic ID d'espace de travail est manquant pour un chemin d'intégration multi-espaces de travail.
• Gemini la clé est marquée comme clé standard sans restriction lorsque des restrictions sont requises.
• Le profil demandé inclut la génération d'images, mais l'adaptateur du fournisseur ne prend pas en charge cette modalité pour les informations d'identification BYOK.

2. Sondes de lecture à faible risque

Utilisez des sondes en lecture seule lorsque le fournisseur les autorise. Un appel de liste de modèles, une vérification des métadonnées de déploiement ou un point de terminaison de capacité de compte peut révéler des échecs d'authentification, de liaison de projet et d'autorisation sans générer de sortie de modèle. Enregistrez à la fois les résultats normalisés et les codes de statut bruts du fournisseur.

Les résultats normalisés recommandés incluent :

• auth_failed : identifiant invalide, révoqué, expiré ou désactivé.
• wrong_project_or_workspace : clé valide, mais non liée au projet ou à l'espace de travail prévu.
• permission_denied : autorisation de point de terminaison, de modèle ou d'administrateur authentifié mais manquante.
• model_unavailable : la clé fonctionne, le modèle ou le déploiement demandé ne fonctionne pas.
• quota_unknown : le runtime fonctionne, mais le quota ne peut pas être inspecté.
• usage_reporting_unavailable : la passerelle ne peut pas concilier l'utilisation côté fournisseur via les informations d'identification fournies.

3. Sondes d'inférence minimales

Au moins une véritable sonde d'inférence est généralement nécessaire pour chaque profil de modèle demandé, car répertorier un modèle n'équivaut pas à être autorisé à l'exécuter. Demandez le consentement explicite du client, définissez un petit budget d'analyse et utilisez le point de terminaison le moins cher qui exerce la fonctionnalité requise.

Gardez les sondes déterministes et ennuyeuses. Pour un profil de texte, envoyez une courte invite avec un plafond de sortie faible. Pour le streaming, vérifiez que le fournisseur renvoie les événements de flux et les métadonnées d'utilisation finale là où prévu. Pour les profils compatibles avec les outils, utilisez une définition d'outil synthétique et confirmez si le fournisseur accepte le schéma de l'outil. Pour la vision, utilisez une petite image de test connue si le fournisseur et la politique le permettent. Évitez les sondes qui stockent des données client sensibles ou nécessitent des invites spécifiques à votre entreprise.

4. Tests négatifs

Les tests négatifs prouvent que les limites politiques sont réelles. Si un locataire est uniquement autorisé à utiliser un profil de modèle défini, le vérificateur doit essayer un modèle, un point de terminaison, un outil ou une région clairement interdit et confirmer que la passerelle le bloque avant que le fournisseur ne le voie. Il s'agit de tests de stratégie de passerelle, et non de tests d'abus de fournisseur.

Ceci est particulièrement important pour les configurations de revendeur et SaaS où IA API provisionnement client crée automatiquement des clés en aval. Une clé en amont fournie par le client ne doit pas contourner la stratégie de passerelle du locataire simplement parce qu'elle dispose d'autorisations de fournisseur plus larges.

Stockez une matrice de capacités, pas un booléen

Le résultat de l'intégration doit être une matrice de capacités attachée à la version des informations d'identification. Cette matrice doit être interrogeable par les pages de routage, d'assistance, de facturation et d'état destinées aux clients.

Une matrice pratique comprend :

• Fournisseur, version des informations d'identification, référence du coffre-fort, locataire et environnement.
• Organisation, projet, espace de travail, point de terminaison, région ou liaison de déploiement observés, le cas échéant.
• Points de terminaison pris en charge : chat, réponses, messages, intégrations, lots, temps réel, images, audio ou équivalents spécifiques au fournisseur.
• Modèles pris en charge et noms de déploiement.
• Fonctionnalités de requête prises en charge : streaming, outils, mode JSON, sortie structurée, vision, audio, mise en cache des invites, tâches par lots.
• En-têtes de limite de débit observés et en-têtes de nouvelle tentative.
• Source de quota connue : administrateur API, en-têtes d'exécution, déclarée par le client ou inconnue.
• Mode de rapport d'utilisation : rapport du fournisseur disponible, mesure de la passerelle uniquement, rapprochement partiel ou non pris en charge.
• Confiance de la vérification : approfondie, superficielle, uniquement lors de l'exécution ou déclarée par le client.
• Dernière sonde réussie, dernière sonde échouée et preuve d'erreur brute.

Le routage devrait consommer cette matrice. Si la matrice indique que la clé prend en charge l'inférence de texte mais pas les tâches par lots, la passerelle doit autoriser le trafic de texte et rejeter le trafic par lots avec un message clair destiné au client. Si le quota ne peut pas être inspecté mais que les sondes d'exécution fonctionnent, les informations d'identification peuvent être marquées comme vérifiées avec une confiance limitée plutôt que de prétendre que la passerelle dispose d'une visibilité complète.

Mapper les résultats de la vérification dans la stratégie de routage

La passerelle ne doit pas acheminer directement du « fournisseur sélectionné par le locataire » vers « utiliser ce secret ». Acheminez de la stratégie de locataire au profil de modèle, du profil de modèle aux exigences de fonctionnalités, et des exigences aux versions d'informations d'identification éligibles.

Par exemple :

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

Cette couche de stratégie protège également la facturation unifiée de l'IA API. BYOK peut affaiblir la facturation centralisée si la passerelle transmet simplement les demandes et fait confiance aux factures des fournisseurs plus tard. Même lorsque les rapports d'utilisation côté fournisseur ne sont pas disponibles, la passerelle doit enregistrer l'utilisation au niveau du locataire, les ID de demande, le profil de modèle, le nombre de jetons normalisés le cas échéant, la fiabilité du rapprochement et tout mode de reporting non pris en charge.

Gérer les échecs avec un langage destiné au client

Les erreurs brutes du fournisseur sont utiles pour l'assistance, mais la plupart des clients ont besoin de conseils de correction directs. Stockez le code d'erreur brut et les en-têtes en interne, puis traduisez l'échec en un message stable.

Revérifiez les informations d'identification après l'intégration

Un contrôle en amont réussi est un instantané, pas une garantie. Les rôles du projet, la politique de l'espace de travail, le quota, l'état de facturation, la disponibilité du modèle et la capacité régionale peuvent changer après l'intégration. La passerelle doit exécuter des vérifications d'état planifiées et des revérifications basées sur des événements.

Déclenchez une nouvelle vérification après :

• 401 ou échecs d'authentification du fournisseur.
• 403 ou réponses avec autorisation refusée.
• 404 réponses de modèle, de déploiement ou de point de terminaison introuvable.
• 429, réponses de dépassement de quota ou de limite de débit en dehors des schémas de trafic normaux.
• Erreurs de facturation du fournisseur, d'organisation, d'espace de travail ou de projet.
• Le client modifie les profils de modèle, les régions, les outils ou la politique de données demandés.

Ne suspendez pas immédiatement l'ensemble du locataire lorsqu'une fonctionnalité tombe en panne. Si le streaming échoue mais que l’inférence sans streaming fonctionne toujours, marquez la fonctionnalité de streaming dégradée et acheminez les charges de travail non streaming éligibles si la politique le permet. S'il manque un seul déploiement Azure, bloquez ce déploiement plutôt que toutes les informations d'identification du fournisseur du client.

Créer une rotation en tant que workflow de vérification parallèle

La rotation ne doit pas être un écrasement aveugle. Créez une nouvelle version des informations d'identification, stockez-la en quarantaine, exécutez les mêmes sondes que l'intégration d'origine et changez de routage de manière atomique uniquement une fois la vérification réussie. Conservez l'ancienne clé dans une courte période de restauration uniquement si le client l'autorise explicitement et si la politique autorise le stockage continu.

Un workflow de rotation sécurisé ressemble à ceci :

1. Le client soumet des informations d'identification et des champs de liaison de remplacement.
2. Gateway stocke le secret en tant que nouvelle version des informations d'identification en quarantaine.
3. Le vérificateur exécute des vérifications statiques, des sondes de lecture, des sondes d'inférence et des tests de stratégie.
4. La matrice de capacités est comparée à la version active.
5. Le client constate des régressions, telles qu'une prise en charge par lots manquante ou une confiance de quota inférieure.
6. La passerelle commute le routage vers la nouvelle version en une seule mise à jour du plan de contrôle.
7. L'ancienne version est révoquée immédiatement ou conservée pendant une courte période de restauration explicite.

L'étape de comparaison est importante. Une clé de remplacement qui peut appeler le modèle de texte de base peut toujours être une régression si elle perd la prise en charge des outils, les rapports d'utilisation, le quota régional ou l'accès à un déploiement de production.

Compromis à rendre explicites

La validation peut entraîner des frais minimes pour le fournisseur. Il est recommandé de demander le consentement, d'afficher un budget d'enquête maximal et d'utiliser un minimum d'invites et de plafonds de sortie. Ne cachez pas les sondes facturables dans « validation ».

L'introspection de l'administrateur améliore la confiance mais augmente le rayon d'explosion. Certains clients fourniront des informations d'identification d'administrateur ou de rapport pour une vérification plus approfondie. D'autres ne fourniront que des clés d'exécution. Prenez en charge les deux, mais étiquetez clairement la confiance qui en résulte.

La sémantique du fournisseur ne se normalisera pas proprement. Une énumération de statut unique est utile pour les flux de produits, mais les équipes d'assistance ont besoin de codes de fournisseur bruts, d'en-têtes, d'ID de demande et de preuves au niveau de l'adaptateur. Conservez les enregistrements normalisés et bruts.

BYOK modifie la responsabilité de facturation. BYOK donne aux clients le contrôle des contrats des fournisseurs, mais il peut réduire la capacité de la passerelle à rapprocher les factures des fournisseurs. La passerelle doit indiquer si la facturation est rapprochée par le fournisseur, mesurée par la passerelle, partielle ou déclarée par le client.

Une intégration stricte ralentit certaines configurations axées sur les ventes. Un mode sandbox limité peut aider, mais il doit être clairement étiqueté, plafonné et bloqué pour la promotion automatique de la production. Le routage de production doit nécessiter une fonctionnalité vérifiée et un mappage de stratégie.

Liste de contrôle de mise en œuvre

• Créez un objet d'identifiant BYOK avec des états de cycle de vie explicites et des versions d'identifiants immuables.
• Collectez les champs de liaison spécifiques au fournisseur avant la vérification.
• Stockez les secrets uniquement dans le coffre-fort des informations d'identification ; enregistrer les empreintes digitales et les références du coffre-fort, pas les clés brutes.
• Exécutez des vérifications statiques avant les appels du fournisseur.
• Exécutez des sondes de lecture lorsque cela est autorisé et conservez les preuves brutes du fournisseur.
• Exécutez une sonde d'inférence minimale par profil de modèle demandé avec le consentement du client et un budget d'analyse.
• Exécutez des tests négatifs de stratégie de passerelle pour les modèles, outils, points de terminaison et régions non autorisés.
• Conserver une matrice de capacités avec un niveau de confiance, pas un booléen.
• Parcourez la politique du locataire et les exigences du profil de modèle, et non directement via un secret sélectionné.
• Exposer les messages d'échec destinés aux clients avec des étapes de correction spécifiques.
• Planifiez des vérifications d'état et déclenchez des revérifications en cas d'erreurs d'exécution.
• Implémenter la rotation sous forme de vérification parallèle suivie d'un commutateur de routage atomique.

Conclusion

Le flux d'intégration BYOK le plus sûr est un vérificateur, pas un formulaire. Une clé de fournisseur fournie par le client doit entrer en quarantaine, prouver sa liaison, ses autorisations, son accès au modèle, ses signaux de quota, son comportement du point de terminaison et ses limites de reporting, puis devenir éligible uniquement pour les fonctionnalités qu'elle prend réellement en charge.

La recommandation pratique est de stocker la vérification sous forme de matrice de capacités, de passer par la politique du locataire et de continuer à revérifier après le début du trafic de production. La prédiction est simple : à mesure que les types de clés de fournisseur, les contrôles d'espace de travail, les quotas régionaux et les autorisations spécifiques au modèle deviennent de plus en plus granulaires, les passerelles qui traitent BYOK comme un téléchargement de secret unique connaîtront davantage d'échecs de production évitables. Les passerelles qui intègrent la vérification des informations d'identification au plan de contrôle intégreront les clients plus lentement au début, mais avec moins de surprises une fois le trafic démarré.

Lecture connexe

• modèle de coffre-fort d'informations d'identification pour séparer l'accès à l'exécution, à l'administration, à la facturation et à BYOK