Clés API IA adaptées au client : isolez les locataires, les budgets et les abus sans prolifération des clés de fournisseur

Les champs exacts varient, mais le principe ne devrait pas changer : chaque demande entrante résout la clé dans la politique du locataire avant son expédition. L'authentification répond « qui appelle ? » La résolution de la politique répond : « Que peut faire cet appelant, combien peut-il dépenser, où la demande peut-elle être acheminée et que doit-il être enregistré ? »

C'est également là que la stratégie produit sémantique est importante. Une plate-forme vendant une API IA pour les agences peut avoir besoin de dimensions client et campagne. Un outil de développement peut nécessiter des dimensions d'espace de travail et de référentiel. Un revendeur peut avoir besoin d'identifiants clients externes correspondant à son système de facturation.

Workflow de création de clé

La création de clés doit être suffisamment déterministe pour l'automatisation et suffisamment stricte pour l'examen de la sécurité.

1. Créez d'abord le dossier client

Ne créez pas de clés orphelines. La clé doit appartenir à un locataire et à un enregistrement client avant d'exister. Pour les plateformes de revendeur, l'enregistrement client doit inclure les identifiants externes du CRM ou du système de facturation du revendeur, les métadonnées du plan, le regroupement des taxes ou des factures si nécessaire, ainsi qu'un champ de statut permettant de suspendre toutes les clés enfants.

2. Joindre un profil de modèle

Un profil de modèle mappe les noms des modèles destinés aux clients aux modèles et fonctionnalités du fournisseur. Par exemple, support-standard peut autoriser un modèle de texte équilibré, la saisie d'images et aucune exécution de code. research-premium peut autoriser des modèles à contexte long, des recherches sur le Web et des plafonds par requête plus élevés.

Ne forcez pas les applications en aval à coder en dur les ID de modèle de fournisseur. Utilisez le profil de passerelle pour gérer la disponibilité, la solution de secours, la tarification et la dépréciation.

3. Définir les limites de dépenses et de tarifs

Utilisez simultanément les budgets et les limites de taux. Un budget mensuel évite les dommages aux factures au fil du temps. Les limites de débit empêchent les abus soudains, les tempêtes de nouvelles tentatives ou les boucles accidentelles de consommer la totalité du budget en quelques minutes.

Les contrôles utiles incluent :

• Budget client mensuel
• Capuchon souple quotidien pour la détection des anomalies.
• Taux de requêtes par clé.
• Taux de jetons d'entrée et de sortie.
• Coût estimé maximum par demande.
• Limites spécifiques aux outils pour la recherche hébergée, le traitement de fichiers ou l'exécution de code.

L'application du budget doit réserver le coût estimé avant l'expédition, régler le coût réel après l'achèvement et libérer la réserve inutilisée. Cela connecte la stratégie clé à la facturation de l'API AI au lieu de traiter la facturation comme une tâche de création de rapports retardée.

4. Générez et stockez correctement le secret

Affichez une fois le secret en texte brut. Stockez uniquement un hachage fort, ainsi qu'un préfixe court ou une empreinte digitale pour la recherche d'assistance. Le préfixe aide les équipes d'assistance à identifier « la clé se terminant par 8F2A » sans voir le secret.

Un modèle de stockage typique est le suivant :

• key_id : identifiant de base de données stable.
• secret_hash : hachage du secret complet à l'aide d'une stratégie de hachage de mot de passe ou de jeton appropriée.
• secret_prefix : préfixe d'affichage court et non sensible.
• empreinte digitale : identifiant déterministe pour la recherche d'audit.
• created_by : utilisateur ou client API partenaire qui a créé la clé.
• statut : actif, épuisé, révoqué, mis en quarantaine, expiré.

Ne stockez jamais les clés du fournisseur en amont sur l'objet clé client. Les identifiants du fournisseur appartiennent à un coffre-fort d'identifiants distinct avec ses propres règles d'accès.

Application du délai de demande

La passerelle doit traiter chaque appel de modèle comme une décision politique suivie d'une répartition par le fournisseur. Un chemin de requête pratique ressemble à ceci :

1. Analyser la clé de passerelle présentée.
2. Recherchez le hachage et l'état de la clé.
3. Résoudre le profil du locataire, du client, de l'application, de l'environnement, du propriétaire et du modèle.
4. Vérifiez si le locataire et le client sont actifs.
5. Valider l'alias de modèle demandé, la modalité, les outils, le mode de conservation, la région et le niveau de service.
6. Estimer le coût de la demande et réserver le budget.
7. Vérifiez les limites de débit et les seuils d'abus.
8. Sélectionnez le mode d'identification en amont : groupé, lié au locataire ou BYOK.
9. Expédier au fournisseur.
10. Capturez l'utilisation, le coût, les références du fournisseur, les erreurs et les signaux de sécurité.
11. Réglez la réservation budgétaire et rédigez l'événement comptable final.

Cette séquence maintient la passerelle responsable du contrat client. Les tableaux de bord des fournisseurs deviennent des éléments de réconciliation, et non la seule source de vérité.

Utiliser les champs du grand livre qui sont réellement utiles plus tard

Un registre de passerelle doit conserver suffisamment de détails pour répondre aux questions d'assistance, de facturation, d'abus et de routage sans nécessiter de stockage d'invites brutes par défaut.

Les champs utiles incluent :

• request_id et trace_id.
• tenant_id, customer_id, application_id et key_id.
• Identifiant de l'utilisateur final, de préférence pseudonyme le cas échéant.
• Alias du modèle demandé par le client.
• Résolution du fournisseur et du modèle en amont.
• Utilisation des entrées, des sorties, du raisonnement, du cache, de l'audio, des images, de la vidéo et des outils, le cas échéant.
• Coût indiqué, montant réservé, coût réglé, devise et version du catalogue de tarification.
• ID de demande du fournisseur, référence du rapport d'utilisation, projet, espace de travail ou dimension de regroupement de clés API si disponible.
• Politique de conservation appliquée.
• Codes de sécurité, d'abus ou de décision politique.
• Catégorie d'erreur et réessayez les métadonnées.

Cette structure prend en charge la rétrofacturation, le support client, la réponse aux incidents et un workflow de gestion des clés API qui peut répondre à la question : « Qu'est-ce que cette clé a fait ? » sans exposer les locataires non liés.

Modes d'identification : regroupés, liés au locataire et BYOK

Identifiants de fournisseur regroupés

En mode par défaut, de nombreuses clés client transitent par un ensemble plus restreint d'informations d'identification du fournisseur. Ceci est simple sur le plan opérationnel et réduit la prolifération du côté des fournisseurs. Cela fonctionne lorsque la passerelle dispose d'une forte attribution de locataire, d'un respect du budget, d'une limitation du débit, d'une isolation contre les abus et de contrôles des limites du cache.

Le compromis est que les rapports côté fournisseur peuvent afficher uniquement les informations d'identification de la passerelle ou le projet du fournisseur. Vous devez joindre les enregistrements du fournisseur aux enregistrements du grand livre de la passerelle pour produire une facturation et des analyses au niveau du client.

Identifiants du fournisseur lié au locataire

Pour les locataires plus grands ou plus risqués, liez un locataire à un projet de fournisseur dédié, un espace de travail, un compte de service ou une clé. Cela donne une séparation plus forte en amont et peut simplifier les rapports côté fournisseur. Il peut également fournir un filet de sécurité strict si le fournisseur prend en charge des limites à cette limite.

Le coût est la complexité opérationnelle. Le provisionnement, la rotation, les limites des fournisseurs, la réponse aux incidents et la réconciliation s'effectuent désormais sur des objets plus en amont.

Apportez votre propre clé

BYOK peut être utile lorsque les clients doivent posséder le compte du fournisseur, négocier leur propre contrat avec le fournisseur ou séparer la facturation du fournisseur. La passerelle applique toujours les profils de modèle, la politique de routage, les analyses et les contrôles au niveau des applications lorsque cela est possible.

Le compromis est la complexité du support. Le compte fournisseur de chaque client peut avoir un accès au modèle, des quotas, des prix, des paramètres de rétention et un statut d'incident différents. La passerelle doit détecter et expliquer clairement ces différences.

Révocation et quarantaine

La révocation doit bloquer immédiatement les nouvelles demandes de clé client sans alterner les informations d'identification du fournisseur en amont sans rapport. C'est l'un des principaux avantages des clés virtuelles.

Utilisez des états distincts pour différentes actions opérationnelles :

• actif : les requêtes sont autorisées.
• draining : l'ancienne clé est acceptée pendant une fenêtre de rotation, mais des avertissements et des événements d'audit sont émis.
• révoqué : les nouvelles demandes sont rejetées définitivement.
• mis en quarantaine : les nouvelles demandes sont bloquées en raison d'un abus, d'un paiement, d'une politique ou d'une réponse à un incident.
• expiré : la clé a dépassé sa durée de vie et doit être remplacée.

La quarantaine devrait être réversible une fois l'incident résolu. La révocation ne devrait généralement pas être réversible, car la restauration d'anciens secrets augmente la confusion et les risques.

Lorsqu'une clé enfreint la politique d'utilisation, enregistrez la raison, l'acteur, l'heure et la portée de l'application. Si la décision a été automatisée, conservez la version de la règle et les signaux qui l'ont déclenchée. Cela garantit que les conversations avec les clients restent factuelles.

Rotation sans interruption de production

La rotation des clés doit utiliser un workflow de chevauchement de deux clés :

1. Créez une clé de remplacement avec le même client, la même application, le même profil de modèle et les mêmes limites, sauf si l'opérateur les modifie intentionnellement.
2. Affichez le nouveau secret une fois.
3. Marquer l'ancienne clé comme drainante.
4. Acceptez les deux clés pendant une période limitée, par exemple 7, 14 ou 30 jours, en fonction du forfait client et des risques.
5. Émettre des avertissements d'utilisation sur la clé de vidange.
6. Avertissez le propriétaire ou le client de l'API partenaire lorsque l'ancienne clé est toujours utilisée à l'approche de la date limite.
7. Révoquer l'ancienne clé à la fin de la fenêtre.
8. Conservez l'attribution sur les deux ID de clé sous le même client et la même application.

Cela évite le mode de défaillance courant où une amélioration de la sécurité se transforme en une interruption de production. La rotation reste un contrôle, mais elle devient un flux de travail opérationnel avec des preuves et des délais.

Surface de l'API partenaire

Si les plates-formes en aval gèrent les clients par programmation, exposez les opérations clés via une API partenaire. L'API doit prendre en charge les clés d'idempotence et les événements d'audit, car le provisionnement s'effectue souvent dans les workflows de facturation, d'intégration ou CRM.

Points de terminaison minimaux :

• POST /clients : créer ou insérer un client.
• POST /customers/{customer_id}/keys : créer une clé.
• GET /customers/{customer_id}/keys : liste les clés et les statuts.
• PATCH /keys/{key_id} : mettre à jour les étendues, le propriétaire, les limites, le profil de modèle ou le statut.
• POST /keys/{key_id}/rotate : créez un remplacement et marquez l'ancienne clé comme drainante.
• POST /keys/{key_id}/revoke : révoquer immédiatement.
• GET /customers/{customer_id}/usage : renvoie l'utilisation et le coût par plage horaire, clé, application, modèle ou dimension utilisateur final.

Chaque demande de mutation doit accepter une clé d'idempotence. Chaque modification doit rédiger un événement d'audit avec l'acteur, la cible, les champs avant et après, l'adresse IP source ou l'identité du client et la raison, le cas échéant.

Quand utiliser des projets ou des espaces de travail de fournisseur

Ne considérez pas les clés de passerelle et les limites du fournisseur comme s'excluant mutuellement. Ils résolvent différents problèmes.

Utiliser les clés de passerelle pour un contrôle normal au niveau du client :

• Attribution par client.
• Clés par application.
• Limites de budget et de taux.
• Suspension rapide.
• Flux de travail de rotation.
• Analyses d'utilisation et rapports pour les revendeurs

Ajoutez des projets de fournisseur, des espaces de travail ou des identifiants de fournisseur dédiés lorsque le client a besoin d'une séparation plus forte :

• Volume mensuel élevé qui mérite des quotas dédiés.
• Des charges de travail réglementées avec des exigences explicites en matière de résidence ou de conservation.
• Séparation contractuelle des factures.
• Budget strict du côté du fournisseur ou garanties de quotas.
• Limites dédiées à la surveillance des abus ou aux examens de sécurité.
• Comptes de fournisseur appartenant aux clients via BYOK.

La valeur par défaut est une isolation renforcée par la passerelle avec des limites matérielles sélectives en amont. Cela permet de simplifier le chemin commun tout en préservant un chemin de remontée pour les clients qui ont besoin de plus de séparation.

Liste de contrôle de mise en œuvre

• Définissez un schéma de clé client avec le locataire, le client, l'application, l'environnement, le propriétaire, le profil de modèle, les limites, la stratégie de rétention et le statut.
• Hashez les secrets au repos et affichez le texte en clair une seule fois.
• Séparez les clés de passerelle du stockage des identifiants du fournisseur en amont.
• Résolvez chaque demande en stratégie avant son envoi.
• Réservez le budget avant les appels du fournisseur et réglez-le une fois que l'utilisation finale est connue.
• Enregistrez l'utilisation avec le client, la clé, l'alias du modèle, le modèle en amont, les catégories de jetons, l'utilisation de l'outil, le coût indiqué, le coût réglé et les références du fournisseur.
• Mettre en œuvre les états actif, drainant, révoqué, mis en quarantaine et expiré.
• Prise en charge du chevauchement de rotation à deux clés.
• Exposer les opérations de l'API partenaire avec des clés d'idempotence.
• Utilisez des projets ou des espaces de travail de fournisseur uniquement lorsque leur coût opérationnel est justifié.

Conclusion exploitable

L'isolation des clients pour l'accès à l'IA doit généralement commencer au niveau de la clé de passerelle, et non au niveau de la clé du fournisseur. La clé de passerelle est le contrat orienté client : elle nomme le locataire, le client, l'application, le profil de modèle, le budget, la limite de débit, la règle de rétention et la politique d'audit. La clé du fournisseur est un détail d'implémentation derrière ce contrat.

Cette architecture offre aux créateurs SaaS et aux plateformes de revendeurs une révocation rapide, une attribution précise, des budgets par client, une rotation contrôlée et des analyses d'utilisation utiles sans créer par défaut un projet de fournisseur en amont pour chaque client. Utilisez des projets en amont, des espaces de travail, des informations d'identification liées au locataire ou BYOK lorsque le risque, le volume, la résidence ou le contrat l'exigent. Pour le chemin ordinaire, appliquez l'isolation des clients dans le grand livre de la passerelle et le moteur de politique, puis rapprochez ensuite les enregistrements du fournisseur.

Lecture connexe

• Provisionnement de l'API partenaire idempotent pour les clients, les clés et les crédits