BYOK-providersleutel-onboarding voor AI API-gateways: controleer klantreferenties voordat verkeer wordt doorgestuurd

Behandel BYOK-onboarding niet als een tekstvak dat een upstream API-sleutel accepteert en routering onmiddellijk inschakelt. In een productie-AI API-gateway hebben door de klant aangeleverde inloggegevens een workflow op het controlevlak nodig: verzamel de providerbinding, plaats de sleutel in quarantaine, voer providerspecifieke tests uit, bouw een mogelijkhedenmatrix en koppel de inloggegevens pas daarna aan het routeringsbeleid van de tenant.

Het lezersprobleem is operationeel: een klant plakt een OpenAI, Anthropic, Gemini of Azure OpenAI-referentie die er geldig uitziet, maar het eerste echte verzoek mislukt omdat de sleutel tot het verkeerde project behoort, geen modeltoegang heeft, het gekozen eindpunt niet kan aanroepen, een zwak quotum heeft of niet de gebruiksgegevens openbaar maakt die nodig zijn voor facturering en afstemming. De gateway moet deze beperkingen ontdekken voordat het klantverkeer ervan afhankelijk is.

Ontwerp de BYOK-referentie als een stateful control-plane-object

Een BYOK-inloggegevens moeten gescheiden zijn van de door de gateway uitgegeven sleutel die applicaties gebruiken. Toepassingen moeten de gateway aanroepen met een stabiele virtuele sleutel, terwijl de gateway die tenant, het productplan, het modelprofiel en het beleid toewijst aan een geverifieerde upstream-referentie. Door deze scheiding blijft de applicatie-integratie stabiel wanneer de klant een upstream-sleutel roteert, van providerproject verandert of een specifieke modelcapaciteit verliest.

Modeleer de upstream-referentie minimaal met deze status:

• ingediend: ontvangen door het besturingsvlak maar nog niet bruikbaar.
• in quarantaine geplaatst: opgeslagen in de kluis en geblokkeerd voor live verkeer terwijl tests worden uitgevoerd.
• geverifieerd: toegestaan voor de specifieke mogelijkheden die de verificatie hebben doorstaan.
• verslechterd: nog steeds bruikbaar voor bepaald verkeer, maar een of meer mogelijkheden, quotasignalen of verwachtingen voor gebruiksrapportage zijn mislukt.
• opgeschort: tijdelijk geblokkeerd na verificatie-, toestemmings-, quota-, facturerings- of beleidsfouten.
• Roulatie vereist: nog steeds bekend bij de gateway, maar moet worden vervangen voordat het productiegebruik wordt voortgezet.
• ingetrokken: verwijderd uit routing en niet langer geaccepteerd als fallback.

Deze statusmachine is van belang voor teams die een LLM met meerdere providers API gateway bouwen, omdat een enkele genormaliseerde 'geldige sleutel'-vlag providerspecifiek gedrag verbergt. De gateway moet weten welke eindpunten, modellen, regio's, modaliteiten en rapportagemodi veilig zijn voor elke tenant.

Verzamel de bindingsvelden van de provider voordat u om het geheim vraagt

Het introductieformulier moet vragen om niet-geheime routeringscontext vóór of naast het geheim. Die context voorkomt dubbelzinnige onderzoeken en levert betere foutmeldingen op.

OpenAI

Verzamel de beoogde organisatie en het beoogde project, de aangevraagde modelprofielen en of de sleutel een gebruikerssleutel of een serviceaccountsleutel is. Een nuttige verificateur zou de projectbinding en -machtigingen moeten controleren, omdat OpenAI op rollen gebaseerde toegangscontrole voor documenten op organisatie- en projectniveau, en API machtigingen worden bepaald door dat model. Voor een aanroep zoals een modellijst kunnen modelleesrechten van de relevante sleutel en rol nodig zijn.

Behandel bereiken voor serviceaccounts als beperkingen, niet als onafhankelijke autoriteit. OpenAI serviceaccountsleutelbereiken kunnen beperken wat het serviceaccount mag doen, maar ze kunnen geen rechten verlenen buiten de toegewezen projectrol. In praktische termen kan een sleutel er smal uitzien en toch mislukken omdat de projectrol het gevraagde model of eindpunt niet toestaat.

Anthropic

Verzamel de beoogde werkruimte-ID wanneer de klant meer dan één werkruimte heeft of identiteitsgekoppelde stromen gebruikt. Anthropic werkruimten kunnen leden, serviceaccounts, API sleutels en resourcelimieten bevatten, en zijn bedoeld om projecten, omgevingen of teams te scheiden onder gecentraliseerde facturering en beheer.

De verifier moet bijhouden of een verzoek een anthropic-workspace-id header nodig had. Volgens de documentatie van Anthropic is deze header mogelijk vereist voor identiteitsgekoppelde sleutelstromen of API-sleutelstromen met meerdere werkruimten. Vermijd ook de veronderstelling dat een runtime-werkruimtegerichte sleutel de resourcelimieten op organisatieniveau kan inspecteren. Sleutels met een werkruimtebereik zijn niet geldig voor sommige beheerdersbewerkingen op organisatieniveau API, zoals inspectie van de snelheidslimiet van de werkruimte.

Gemini

Verzamel of de sleutel afkomstig is van AI Studio of een Google Cloud-project, de beoogde projectcontext, de toegestane API's en eventuele beperkingen die de klant verwacht. Volgens de Gemini API-sleuteldocumentatie van Google is elke Gemini API-sleutel gekoppeld aan een Google Cloud-project en worden er nieuwe AI Studio-sleutels gemaakt als verificatiesleutels. Er staat ook dat onbeperkte standaardsleutels worden afgewezen door de Gemini API als onderdeel van de stap af van onveilige, onbeperkte sleutels.

De onboarding-UI moet onveilige, onbeperkte standaardsleutels markeren in plaats van klanten aan te moedigen de beperkingen te versoepelen totdat het onderzoek is geslaagd. Google Cloud API-sleutelrichtlijnen bevelen API beperkingen aan, waarbij sleutels in queryparameters worden vermeden, onnodige sleutels worden verwijderd en sleutels niet aan opslagplaatsen worden vastgelegd. Gemini auth-sleutels vormen een speciale productie-uitzondering omdat Gemini API geen Google Cloud-projectresources creëert, maar de verificateur moet nog steeds het sleuteltype en de beperkingsstatus registreren.

Azure OpenAI

Verzamel eindpunt, implementatienaam, API versie, regio en abonnementscontext als de klant deze kan leveren. Azure OpenAI routeert door door de klant gemaakte implementaties, dus een algemene modelnaam is niet voldoende. Een sleutel kan geldig zijn voor de bron terwijl de aangevraagde implementatienaam ontbreekt, zich in een andere regio bevindt of gebonden is aan een modelversie die de gateway niet verwacht.

Azure OpenAI-quotum wordt toegewezen per abonnement, regio, model en implementatietype in TPM-eenheden. Toegewezen TPM-toewijzingen aan implementatiesnelheidslimieten, terwijl RPM ook wordt afgedwongen. Runtime-reacties kunnen nuttige headers met snelheidslimieten blootleggen, zoals resterende aanvragen, resterende tokens en opnieuw proberen na ms. Leg deze signalen vast tijdens tests en runtime-monitoring.

Verificatie uitvoeren in lagen

Een goede preflightsuite begint goedkoop en met weinig risico, en gebruikt vervolgens slechts één minimaal factureerbaar onderzoek als de klant daarmee heeft ingestemd. Sommige providers laten niet genoeg introspectie zien via runtimesleutels, dus een succesvol onboardingresultaat moet een betrouwbaarheidsniveau omvatten, en niet alleen maar slagen of falen.

1. Statische controles

Valideer duidelijke opmaakproblemen, ontbrekende velden, incompatibele eindpuntvormen, niet-ondersteunde regio's en onjuist opgemaakte implementatienamen voordat u de provider belt. Statische controles mogen nooit het onbewerkte geheim registreren. Bewaar in plaats daarvan een vingerafdruk, aanmaakbron, tenant-ID, provider en kluisreferentie.

Voorbeelden:

• Het Azure-eindpunt komt niet overeen met het verwachte bron-URL-patroon.
• De naam van de Azure-implementatie is leeg, ook al is het aangevraagde modelprofiel toegewezen aan Azure OpenAI.
• Anthropic werkruimte-ID ontbreekt voor een onboardingpad voor meerdere werkruimten.
• Gemini sleutel wordt gemarkeerd als onbeperkte standaardsleutel wanneer beperkingen vereist zijn.
• Het aangevraagde profiel omvat het genereren van afbeeldingen, maar de provideradapter ondersteunt deze modaliteit voor BYOK-inloggegevens niet.

2. Leesprobes met laag risico

Gebruik alleen-lezen tests als de provider dit toestaat. Een aanroep van een modellijst, een controle van de metagegevens van de implementatie of een eindpunt voor accountmogelijkheden kunnen authenticatie-, projectbinding- en toestemmingsfouten aan het licht brengen zonder modeluitvoer te genereren. Registreer zowel genormaliseerde resultaten als onbewerkte statuscodes van de provider.

Aanbevolen genormaliseerde resultaten zijn onder meer:

• auth_failed: ongeldige, ingetrokken, verlopen of uitgeschakelde inloggegevens.
• wrong_project_or_workspace: geldige sleutel, maar niet gebonden aan het beoogde project of de beoogde werkruimte.
• permission_denied: geverifieerd maar er ontbreken eindpunt-, model- of beheerdersrechten.
• model_unavailable: sleutel werkt, aangevraagd model of implementatie niet.
• quota_unknown: runtime werkt, maar quota kunnen niet worden geïnspecteerd.
• usage_reporting_unavailable: gateway kan het gebruik aan de providerzijde niet afstemmen via de opgegeven inloggegevens.

3. Minimale inferentiesondes

Normaal gesproken is er voor elk aangevraagd modelprofiel ten minste één echte inferentietest nodig, omdat het vermelden van een model niet hetzelfde is als het mogen uitvoeren ervan. Vraag expliciete toestemming van de klant, stel een klein testbudget in en gebruik het goedkoopste eindpunt dat over de vereiste capaciteit beschikt.

Houd de onderzoeken deterministisch en saai. Voor een tekstprofiel stuurt u een korte prompt met een lage uitvoerlimiet. Controleer voor streaming of de provider streamgebeurtenissen en metagegevens over het uiteindelijke gebruik retourneert waar verwacht. Voor profielen die geschikt zijn voor tools gebruikt u een synthetische tooldefinitie en bevestigt u of de provider het toolschema accepteert. Gebruik voor zicht een klein bekend testbeeld als de aanbieder en het beleid dit toestaan. Vermijd onderzoeken waarbij gevoelige klantgegevens worden opgeslagen of die bedrijfsspecifieke aanwijzingen vereisen.

4. Negatieve tests

Negatieve tests bewijzen dat beleidsgrenzen reëel zijn. Als een tenant alleen een gedefinieerd modelprofiel mag gebruiken, moet de verificateur een duidelijk niet-toegestaan ​​model, eindpunt, tool of regio proberen en bevestigen dat de gateway dit blokkeert voordat de provider het ziet. Dit zijn gateway-beleidstests, geen tests voor providermisbruik.

Dit is vooral belangrijk voor reseller- en SaaS-configuraties waarbij AI API klantregistratie automatisch downstream-sleutels maakt. Een door de klant geleverde upstream-sleutel mag het gatewaybeleid van de tenant niet omzeilen alleen maar omdat deze bredere providerrechten heeft.

Sla een mogelijkhedenmatrix op, geen Booleaanse waarde

De output van onboarding moet een mogelijkhedenmatrix zijn die is gekoppeld aan de inloggegevensversie. Die matrix moet doorzoekbaar zijn via routerings-, ondersteunings-, facturerings- en klantgerichte statuspagina's.

Een praktische matrix omvat:

• Provider, inloggegevensversie, kluisreferentie, tenant en omgeving.
• Waargenomen organisatie-, project-, werkruimte-, eindpunt-, regio- of implementatiebinding, indien beschikbaar.
• Ondersteunde eindpunten: chat, reacties, berichten, insluitingen, batches, realtime, afbeeldingen, audio of providerspecifieke equivalenten.
• Ondersteunde modellen en implementatienamen.
• Ondersteunde verzoekfuncties: streaming, tools, JSON-modus, gestructureerde uitvoer, visie, audio, promptcaching, batchtaken.
• Waargenomen headers met snelheidslimiet en headers voor nieuwe pogingen.
• Bekende quotabron: beheerder API, runtime headers, door de klant aangegeven of onbekend.
• Gebruiksrapportagemodus: providerrapport beschikbaar, meting alleen op gateway, gedeeltelijke afstemming of niet ondersteund.
• Verificatievertrouwen: diep, oppervlakkig, alleen runtime of door de klant aangegeven.
• Laatste succesvolle test, laatste mislukte test en onbewerkt foutbewijs.

Routing zou deze matrix moeten gebruiken. Als de matrix zegt dat de sleutel tekstinferentie ondersteunt, maar geen batchtaken, moet de gateway tekstverkeer toestaan ​​en batchverkeer weigeren met een duidelijke klantgerichte boodschap. Als de quota niet kunnen worden geïnspecteerd, maar runtime-tests werken, kan de referentie worden gemarkeerd als geverifieerd met beperkt vertrouwen in plaats van te doen alsof de gateway volledige capaciteitszichtbaarheid heeft.

Verificatieresultaten verwerken in routeringsbeleid

De gateway mag niet rechtstreeks van 'tenant geselecteerde provider' naar 'gebruik dit geheim' routeren. Route van tenantbeleid naar modelprofiel, van modelprofiel naar capaciteitsvereisten en van vereisten naar in aanmerking komende referentieversies.

Bijvoorbeeld:

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

Deze beleidslaag beschermt ook unified AI API facturering. BYOK kan de gecentraliseerde facturering verzwakken als de gateway eenvoudigweg verzoeken doorgeeft en de facturen van de provider later vertrouwt. Zelfs als gebruiksrapporten aan de providerzijde niet beschikbaar zijn, moet de gateway het gebruik op tenantniveau registreren, de aanvraag-ID's, het modelprofiel, het genormaliseerde aantal tokens waar beschikbaar, het vertrouwen in de afstemming en elke niet-ondersteunde rapportagemodus.

Behandel fouten met klantgericht taalgebruik

Ruwe providerfouten zijn nuttig voor ondersteuning, maar de meeste klanten hebben directe hulp bij herstel nodig. Sla de onbewerkte foutcode en headers intern op en vertaal de fout vervolgens in een stabiel bericht.

Controleer de inloggegevens opnieuw na de introductie

Een succesvolle preflight is een momentopname en geen garantie. Projectrollen, werkruimtebeleid, quota, factureringsstatus, modelbeschikbaarheid en regionale capaciteit kunnen na onboarding veranderen. De gateway moet geplande statuscontroles en gebeurtenisgestuurde hercontroles uitvoeren.

Activeer een nieuwe controle na:

• 401- of providerverificatiefouten.
• 403 of toestemming geweigerde reacties.
• 404-model-, implementatie- of eindpunt-niet-gevonden reacties.
• 429 reacties, quotumoverschrijding of snelheidslimietreacties buiten de normale verkeerspatronen.
• Facturerings-, organisatie-, werkruimte- of projectfouten aan de provider.
• Klantwijzigingen in aangevraagde modelprofielen, regio's, tools of gegevensbeleid.

Schort niet onmiddellijk de hele tenant op als er één mogelijkheid kapot gaat. Als streaming mislukt maar niet-streaming-inferentie nog steeds werkt, markeer dan de streamingcapaciteit als verslechterd en stuur in aanmerking komende niet-streaming-workloads door als het beleid dit toestaat. Als er één Azure-implementatie ontbreekt, blokkeer dan die implementatie in plaats van alle inloggegevens van de provider van de klant.

Roulatie bouwen als een parallelle verificatieworkflow

Rotatie mag geen blinde overschrijving zijn. Maak een nieuwe referentieversie, bewaar deze in quarantaine, voer dezelfde tests uit als bij de oorspronkelijke onboarding en schakel de routering pas atomair over nadat de verificatie is geslaagd. Bewaar de oude sleutel alleen in een korte terugdraaiperiode als de klant dit expliciet toestaat en het beleid voortdurende opslag toestaat.

Een veilige rotatieworkflow ziet er als volgt uit:

1. Klant dient vervangende inloggegevens en bindende velden in.
2. Gateway slaat het geheim op als een nieuwe inloggegevensversie in quarantaine.
3. Verifier voert statische controles uit, leestests, gevolgtrekkingstests en beleidstests.
4. De capaciteitsmatrix wordt vergeleken met de actieve versie.
5. De klant ziet eventuele regressies, zoals ontbrekende batchondersteuning of een lager quotumvertrouwen.
6. Gateway-switches routeren naar de nieuwe versie in één update van het besturingsvlak.
7. De oude versie wordt onmiddellijk ingetrokken of bewaard voor een korte, expliciete terugdraaiperiode.

De vergelijkingsstap is belangrijk. Een vervangende sleutel die het basistekstmodel kan aanroepen, kan nog steeds een regressie zijn als deze toolondersteuning, gebruiksrapportage, regionale quota of toegang tot een productie-implementatie verliest.

Afwegingen om expliciet te maken

Verificatie kan kleine providerkosten met zich meebrengen. De aanbeveling is om toestemming te vragen, een maximaal testbudget weer te geven en minimale prompts en uitvoerlimieten te gebruiken. Verberg factureerbare onderzoeken niet binnen 'validatie'.

Introspectie door de beheerder verbetert het vertrouwen, maar vergroot de straal van de explosie. Sommige klanten verstrekken beheerders- of rapportagegegevens voor diepgaandere verificatie. Anderen bieden alleen runtime-sleutels. Ondersteun beide, maar noem het resulterende vertrouwen duidelijk.

De semantiek van de provider zal niet netjes worden genormaliseerd. Een enkele statusopsomming is handig voor productstromen, maar ondersteuningsteams hebben onbewerkte providercodes, headers, verzoek-ID's en bewijsmateriaal op adapterniveau nodig. Bewaar zowel genormaliseerde als onbewerkte records.

BYOK verandert de factureringsverantwoordelijkheid. BYOK geeft klanten controle over het providercontract, maar kan het vermogen van de gateway om leveranciersfacturen af te stemmen verminderen. De gateway moet aangeven of de facturering door de provider is afgestemd, door de gateway is gemeten, gedeeltelijk of door de klant is gedeclareerd.

Strikte introductie vertraagt sommige verkoopgestuurde instellingen. Een beperkte sandbox-modus kan helpen, maar deze moet duidelijk worden gelabeld, afgedekt en geblokkeerd voor automatische productiepromotie. Voor productieroutering zijn geverifieerde mogelijkheden en beleidstoewijzing vereist.

Implementatiechecklist

• Maak een BYOK-inloggegevensobject met expliciete levenscyclusstatussen en onveranderlijke inloggegevensversies.
• Verzamel providerspecifieke bindingsvelden vóór verificatie.
• Bewaar geheimen alleen in de kluis met inloggegevens; registreer vingerafdrukken en kluisreferenties, geen onbewerkte sleutels.
• Voer statische controles uit voordat de provider belt.
• Voer leestests uit waar toegestaan en bewaar onbewerkt bewijs van de provider.
• Voer één minimale inferentietest uit per aangevraagd modelprofiel met toestemming van de klant en een testbudget.
• Voer negatieve tests voor het gatewaybeleid uit voor niet-toegestane modellen, tools, eindpunten en regio's.
• Houd een mogelijkhedenmatrix vast met een betrouwbaarheidsniveau, niet met een Booleaanse waarde.
• Route door het tenantbeleid en de modelprofielvereisten, niet rechtstreeks door een geselecteerd geheim.
• Maak klantgerichte foutberichten zichtbaar met specifieke herstelstappen.
• Plan statuscontroles en activeer nieuwe controles op basis van runtimefouten.
• Implementeer rotatie als parallelle verificatie gevolgd door een atomaire routeringsschakelaar.

Conclusie

Het veiligste BYOK-onboardingproces is een verificatie, geen formulier. Een door de klant geleverde providersleutel moet in quarantaine worden geplaatst, de binding, machtigingen, modeltoegang, quotasignalen, eindpuntgedrag en rapportagelimieten bewijzen, en vervolgens alleen in aanmerking komen voor de mogelijkheden die deze daadwerkelijk ondersteunt.

De praktische aanbeveling is om verificatie op te slaan als een mogelijkhedenmatrix, het tenantbeleid te doorlopen en opnieuw te controleren nadat het productieverkeer is begonnen. De voorspelling is eenvoudig: naarmate sleuteltypen van de provider, werkruimtecontroles, regionale quota's en modelspecifieke machtigingen steeds gedetailleerder worden, zullen gateways die BYOK behandelen als een eenmalige geheime upload meer vermijdbare productiefouten zien. Gateways die verificatie van inloggegevens onderdeel maken van het controlevlak, zullen klanten in eerste instantie langzamer aan boord krijgen, maar met minder verrassingen nadat het verkeer is gestart.

Gerelateerd lezen

• Inloggegevenskluispatroon voor het scheiden van runtime-, beheerders-, facturerings- en BYOK-toegang