BYOK Provider-Key Onboarding for AI API Gateways: Verify Customer Credentials Before Routing Traffic

Nepovažujte registraci BYOK za textové pole, které přijímá upstream klíč API a okamžitě umožňuje směrování. V produkční bráně AI API potřebují pověření zadaná zákazníkem pracovní postup na řídicí úrovni: shromážděte vazbu poskytovatele, umístěte klíč do karantény, spusťte testy specifické pro poskytovatele, vytvořte matici schopností a teprve poté připojte pověření k zásadám směrování tenanta.

Problém se čtečkou je funkční: zákazník vloží pověření OpenAI, Anthropic, Gemini nebo Azure OpenAI, které vypadá jako platné, ale první skutečný požadavek se nezdaří, protože klíč patří nesprávnému projektu, nemá přístup k modelu, nemůže volat vybraný koncový bod, má slabou kvótu nebo nezveřejňuje údaje o využití potřebné pro fakturaci a odsouhlasení. Brána by měla tato omezení objevit dříve, než na nich bude zákaznický provoz záviset.

Navrhněte pověření BYOK jako stavový objekt řídicí roviny

Přihlašovací údaje BYOK by měly být odděleny od klíče vydaného bránou, který aplikace používají. Aplikace by měly volat bránu se stabilním virtuálním klíčem, zatímco brána mapuje tohoto tenanta, produktový plán, profil modelu a zásady na ověřené upstream pověření. Toto oddělení udržuje integraci aplikací stabilní, když zákazník otočí upstream klíč, změní projekty poskytovatele nebo ztratí schopnost konkrétního modelu.

Pověření pro upstream modelujte minimálně s těmito stavy:

• submitted: přijato kontrolní rovinou, ale zatím není použitelné.
• karanténa: uloženo v trezoru a zablokováno před živým provozem, zatímco sondy běží.
• verified: povoleno pro konkrétní funkce, které prošly ověřením.
• degraded: stále použitelné pro určitý provoz, ale jedna nebo více funkcí, signálů kvót nebo očekávání ohledně hlášení využití selhala.
• suspended: dočasně zablokováno po chybách ověření, povolení, kvóty, fakturace nebo zásad.
• rotation-required: brána je stále známá, ale musí být vyměněna, než bude pokračovat v produkčním provozu.
• revoked: odstraněno ze směrování a již není přijímáno jako záložní řešení.

Tento stavový stroj je důležitý pro týmy, které budují multi-poskytovatel LLM API bránu, protože jeden normalizovaný příznak „platný klíč“ skryje chování specifické pro poskytovatele. Brána potřebuje vědět, které koncové body, modely, oblasti, modality a režimy hlášení jsou pro každého tenanta bezpečné.

Než požádáte o tajný kód, shromážděte pole vazby poskytovatele

Formulář pro registraci by měl před tajným kódem nebo vedle něj vyžadovat netajný směrovací kontext. Tento kontext zabraňuje nejednoznačným sondám a vytváří lepší chybové zprávy.

OpenAI

Shromážděte zamýšlenou organizaci a projekt, požadované profily modelů a zda se jedná o klíč uživatele nebo klíč servisního účtu. Užitečný ověřovatel by měl kontrolovat vazbu projektu a oprávnění, protože OpenAI dokumenty řízení přístupu na základě rolí na úrovni organizace a projektu a API oprávnění se řídí tímto modelem. Volání, jako je výpis modelu, může vyžadovat oprávnění ke čtení modelu od příslušného klíče a role.

U servisních účtů považujte rozsahy za omezení, nikoli za nezávislou autoritu. OpenAI Rozsahy klíče servisního účtu mohou omezit, co může servisní účet dělat, ale nemohou udělovat oprávnění mimo přiřazenou roli projektu. Z praktického hlediska může klíč vypadat úzce vymezený a přesto selhat, protože role projektu neumožňuje požadovaný model nebo koncový bod.

Anthropic

Pokud má zákazník více než jeden pracovní prostor nebo používá toky propojené s identitou, shromážděte zamýšlené ID pracovního prostoru. Pracovní prostory Anthropic mohou obsahovat členy, servisní účty, klíče API a limity zdrojů a jsou určeny k oddělení projektů, prostředí nebo týmů pod centralizovanou fakturací a správou.

Ověřovatel by měl zachovat, zda požadavek vyžadoval anthropic-workspace-id záhlaví. Dokumentace Anthropic říká, že toky klíčů propojené s identitou nebo s více pracovními prostory API mohou tuto hlavičku vyžadovat. Vyhněte se také předpokladu, že klíč s rozsahem pracovního prostoru za běhu může kontrolovat limity prostředků na úrovni organizace. Klíče s rozsahem pracovního prostoru nejsou platné pro některé operace správce na úrovni organizace API, jako je kontrola limitu rychlosti pracovního prostoru.

Gemini

Zjistěte, zda klíč pochází z AI Studio nebo Google cloudového projektu, zamýšlený kontext projektu, povolená rozhraní API a veškerá omezení, která zákazník očekává. Dokumentace klíče Google Gemini API říká, že každý klíč Gemini API je spojen s cloudovým projektem Google a nové klíče AI Studio jsou vytvořeny jako ověřovací klíče. Také říká, že neomezené standardní klíče jsou odmítnuty Gemini API jako součást odklonu od nebezpečných neomezených klíčů.

Uživatelské rozhraní pro registraci by mělo označovat nebezpečné neomezené standardní klíče místo toho, aby nabádalo zákazníky k uvolnění omezení, dokud sonda neprojde. Google Cloud API-key guidelines doporučují API omezení, vyhýbat se klíčům v parametrech dotazu, mazat nepotřebné klíče a neposílat klíče do úložišť. Gemini auth klíče jsou speciální produkční výjimkou, protože Gemini API nevytváří Google prostředky cloudového projektu, ale ověřovatel by měl přesto zaznamenat typ klíče a pozici omezení.

Azur OpenAI

Shromažďujte koncový bod, název nasazení, API verzi, oblast a kontext předplatného, pokud je může zákazník poskytnout. Azure OpenAI směruje přes nasazení vytvořená zákazníky, takže obecný název modelu nestačí. Klíč může být platný pro zdroj, zatímco požadovaný název nasazení chybí, v jiné oblasti nebo je vázán na verzi modelu, kterou brána neočekává.

Azure OpenAI je přiřazena podle předplatného, regionu, modelu a typu nasazení v jednotkách TPM. Přiřazené mapy TPM k limitům rychlosti nasazení, zatímco RPM je také vynuceno. Odpovědi za běhu mohou odhalit užitečná záhlaví s omezením rychlosti, jako jsou zbývající požadavky, zbývající tokeny a opakování po ms. Zachyťte tyto signály během sond a monitorování za běhu.

Spustit ověření ve vrstvách

Dobrá sada pro kontrolu před výstupem začíná levně a s nízkým rizikem a poté použije jednu minimální účtovanou sondu pouze se souhlasem zákazníka. Někteří poskytovatelé nevystavují dostatek introspekce prostřednictvím runtime klíčů, takže úspěšný výsledek registrace by měl zahrnovat úroveň spolehlivosti, nikoli pouze projít nebo nepropadnout.

1. Statické kontroly

Před voláním poskytovatele ověřte zjevné problémy s formátováním, chybějící pole, nekompatibilní tvary koncových bodů, nepodporované oblasti a nesprávně naformátované názvy nasazení. Statické kontroly by nikdy neměly zaznamenávat nezpracované tajemství. Místo toho uložte otisk prstu, zdroj vytvoření, ID tenanta, poskytovatele a odkaz na trezor.

Příklady:

• Koncový bod Azure neodpovídá očekávanému vzoru adresy URL zdroje.
• Název nasazení Azure je prázdný, i když se požadovaný profil modelu mapuje na Azure OpenAI.
• Anthropic ID pracovního prostoru chybí pro cestu k zápisu do více pracovních prostorů.
Klíč
• Gemini je označen jako standardní klíč bez omezení, pokud jsou vyžadována omezení.
• Požadovaný profil zahrnuje generování obrázků, ale adaptér poskytovatele tuto modalitu pro přihlašovací údaje BYOK nepodporuje.

2. Čtecí sondy s nízkým rizikem

Používejte sondy pouze pro čtení tam, kde to poskytovatel umožňuje. Volání seznamu modelů, kontrola metadat nasazení nebo koncový bod schopnosti účtu mohou odhalit selhání ověřování, vazby projektu a oprávnění bez generování výstupu modelu. Zaznamenávejte jak normalizované výsledky, tak nezpracované kódy stavu poskytovatele.

Doporučené normalizované výsledky zahrnují:

• auth_failed: neplatné, zrušené, vypršela platnost nebo deaktivované pověření.
• wrong_project_or_workspace: platný klíč, ale není vázán na zamýšlený projekt nebo pracovní prostor.
• permission_denied: ověřeno, ale chybí koncový bod, model nebo oprávnění správce.
• model_unavailable: klíč funguje, požadovaný model nebo nasazení ne.
• quota_unknown: runtime funguje, ale kvótu nelze zkontrolovat.
• usage_reporting_unavailable: brána nemůže sladit použití na straně poskytovatele prostřednictvím dodaných přihlašovacích údajů.

3. Minimální inferenční sondy

Pro každý požadovaný profil modelu je obvykle nutná alespoň jedna skutečná inferenční sonda, protože uvedení modelu není totéž jako povolení jej provozovat. Požádejte o výslovný souhlas zákazníka, nastavte malý rozpočet na testování a použijte nejlevnější koncový bod, který vykonává požadovanou funkci.

Udržujte sondy deterministické a nudné. U textového profilu odešlete krátkou výzvu s nízkým výstupem. U streamování ověřte, že poskytovatel vrací události streamu a metadata konečného využití tam, kde se to očekává. U profilů vhodných pro nástroje použijte syntetickou definici nástroje a potvrďte, zda poskytovatel akceptuje schéma nástroje. Pro vidění použijte malý známý testovací obrázek, pokud to poskytovatel a zásady umožňují. Vyhněte se sondám, které uchovávají citlivá zákaznická data nebo vyžadují výzvy specifické pro firmu.

4. Negativní testy

Negativní testy dokazují, že hranice zásad jsou skutečné. Pokud má tenant povoleno používat pouze definovaný profil modelu, měl by ověřovatel vyzkoušet jasně nepovolený model, koncový bod, nástroj nebo oblast a potvrdit, že je brána zablokuje, než to poskytovatel uvidí. Toto jsou testy zásad brány, nikoli testy zneužití poskytovatele.

To je zvláště důležité pro nastavení distributora a SaaS, kde AI API customer provisioning vytváří následné klíče automaticky. Zákazníkem dodaný upstream klíč by neměl obcházet zásady brány tenanta jen proto, že má širší oprávnění poskytovatele.

Uložte matici schopností, nikoli booleovskou hodnotu

Výstupem onboardingu by měla být matice schopností připojená k verzi pověření. Tato matice by měla být dotazovatelná pomocí směrování, podpory, fakturace a stavových stránek pro zákazníky.

Praktická matrice zahrnuje:

• Poskytovatel, verze pověření, reference trezoru, tenant a prostředí.
• Sledovaná organizace, projekt, pracovní prostor, koncový bod, oblast nebo vazba nasazení, pokud je k dispozici.
• Podporované koncové body: chat, odpovědi, zprávy, vkládání, dávky, v reálném čase, obrázky, zvuk nebo ekvivalenty specifické pro poskytovatele.
• Podporované modely a názvy nasazení.
• Podporované funkce požadavků: streamování, nástroje, režim JSON, strukturovaný výstup, vidění, zvuk, rychlé ukládání do mezipaměti, dávkové úlohy.
• Dodržovaná záhlaví s omezením rychlosti a opakujte záhlaví.
• Známý zdroj kvót: admin API, runtime headers, customer-deklared, or unknown.
• Režim hlášení využití: dostupný přehled poskytovatele, měření pouze pomocí brány, částečné odsouhlasení nebo není podporováno.
• Důvěryhodnost ověření: hluboká, mělká, pouze za běhu nebo deklarovaná zákazníkem.
• Poslední úspěšné vyšetření, poslední neúspěšné vyšetření a nezpracované důkazy o chybě.

Směrování by mělo spotřebovat tuto matici. Pokud matice říká, že klíč podporuje textové odvození, ale ne dávkové úlohy, brána by měla umožnit textový provoz a odmítnout dávkový provoz s jasnou zprávou pro zákazníka. Pokud kvótu nelze zkontrolovat, ale běhové sondy fungují, lze pověření označit jako ověřené s omezenou spolehlivostí, nikoli předstírat, že brána má plnou kapacitu.

Namapujte výsledky ověření do zásad směrování

Brána by neměla směrovat přímo od „poskytovatele vybraného nájemcem“ k „použít toto tajemství“. Cesta od zásad tenanta k profilu modelu, od profilu modelu k požadavkům na funkce a od požadavků k vhodným verzím pověření.

Například:

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

Tato vrstva zásad také chrání unified AI API billing. BYOK může oslabit centralizované účtování, pokud brána jednoduše projde požadavky a důvěřuje fakturám poskytovatelů později. I když zprávy o využití na straně poskytovatele nejsou k dispozici, brána by měla zaznamenávat využití na úrovni tenanta, ID požadavků, profil modelu, normalizované počty tokenů, pokud jsou k dispozici, spolehlivost odsouhlasení a jakýkoli nepodporovaný režim hlášení.

Řešit selhání pomocí jazyka, který je v kontaktu se zákazníky

Nezpracované chyby poskytovatele jsou užitečné pro podporu, ale většina zákazníků potřebuje přímé pokyny k nápravě. Uložte nezpracovaný chybový kód a hlavičky interně a poté selhání převeďte do stabilní zprávy.

Po registraci znovu zkontrolujte přihlašovací údaje

Úspěšná kontrola před výstupem je snímek, nikoli záruka. Role projektu, politika pracovního prostoru, kvóta, stav fakturace, dostupnost modelu a regionální kapacita se mohou po přihlášení změnit. Brána by měla provádět naplánované kontroly stavu a opakované kontroly řízené událostmi.

Spustit novou kontrolu po:

• Chyby ověření 401 nebo poskytovatele.
• 403 nebo odpovědi se zamítnutím povolení.
• Model 404, nasazení nebo odpovědi nenalezen koncový bod.
• 429, odezvy s překročením kvóty nebo s limitem sazby mimo běžné vzorce provozu.
• Chyby fakturace poskytovatele, organizace, pracovního prostoru nebo projektu.
• Zákazník změní požadované profily modelů, regiony, nástroje nebo zásady dat.

Nezastavujte okamžitě celého tenanta, když jedna funkce přestane fungovat. Pokud streamování selže, ale neodvozování bez streamování stále funguje, označte schopnost streamování za sníženou a směrujte vhodné nestreamingové úlohy, pokud to zásady umožňují. Pokud chybí jediné nasazení Azure, zablokujte toto nasazení, nikoli všechny přihlašovací údaje poskytovatele zákazníka.

Vytvoření rotace jako pracovního postupu paralelního ověřování

Otočení by nemělo být slepé přepsání. Vytvořte novou verzi pověření, uložte ji do karantény, spusťte stejné sondy jako původní začlenění a atomicky přepněte směrování až po úspěšném ověření. Starý klíč ponechejte v krátkém okně vrácení pouze v případě, že to zákazník výslovně povolí a zásady umožňují další ukládání.

Pracovní postup bezpečného střídání vypadá takto:

1. Zákazník odešle náhradní pole pověření a závazná pole.
2. Brána ukládá tajemství jako novou verzi pověření v karanténě.
3. Verifier spouští statické kontroly, čtecí testy, inferenční testy a testy zásad.
4. Matice schopností je porovnána s aktivní verzí.
5. Zákazník vidí jakékoli regrese, například chybějící dávkovou podporu nebo nižší spolehlivost kvóty.
6. Brána přepne směrování na novou verzi jednou aktualizací řídicí roviny.
7. Stará verze je okamžitě odvolána nebo zachována po krátké, explicitní okno vrácení.

Krok porovnání je důležitý. Náhradní klíč, který může volat základní textový model, může být stále regresí, pokud ztratí podporu nástrojů, hlášení využití, regionální kvótu nebo přístup k produkčnímu nasazení.

Výrazy, které je třeba uvést na pravou míru

Ověření může poskytovateli účtovat malé poplatky. Doporučuje se požádat o souhlas, ukázat maximální rozpočet na testování a používat minimální výzvy a omezení výstupu. Neschovávejte fakturovatelné sondy do „ověření“.

Introspekce administrátora zvyšuje důvěru, ale zvyšuje rádius výbuchu. Někteří zákazníci poskytnou pověření správce nebo hlášení pro hlubší ověření. Ostatní poskytnou pouze runtime klíče. Podpořte obojí, ale výslednou důvěru jasně označte.

Sémantika poskytovatelů se nenormalizuje čistě. Jediný stavový výčet je užitečný pro toky produktů, ale týmy podpory potřebují nezpracované kódy poskytovatelů, záhlaví, ID požadavků a důkazy na úrovni adaptéru. Zachovejte normalizované i nezpracované záznamy.

BYOK mění odpovědnost za fakturaci. BYOK poskytuje zákazníkům kontrolu nad smlouvou poskytovatele, ale může snížit schopnost brány odsouhlasit faktury poskytovatele. Brána by měla odhalit, zda je fakturace odsouhlasená poskytovatelem, měřená bránou, částečná nebo deklarovaná zákazníkem.

Přísné přihlášení zpomaluje některá nastavení řízená prodejem. Omezený režim izolovaného prostoru může pomoci, ale měl by být jasně označen, omezen a zablokován v automatické propagaci produkce. Produkční směrování by mělo vyžadovat ověřené schopnosti a mapování zásad.

Kontrolní seznam implementace

• Vytvořte objekt pověření BYOK s explicitními stavy životního cyklu a neměnnými verzemi pověření.
• Před ověřením shromážděte závazná pole specifická pro poskytovatele.
• Ukládat tajemství pouze do trezoru pověření; protokolovat otisky prstů a odkazy na trezor, nikoli nezpracované klíče.
• Před voláním poskytovatele spusťte statické kontroly.
• Spouštět sondy čtení tam, kde je to povoleno, a uchovávat nezpracované důkazy poskytovatele.
• Spusťte jednu minimální inferenční sondu na požadovaný profil modelu se souhlasem zákazníka a rozpočtem na sondu.
• Proveďte negativní testy zásad brány pro nepovolené modely, nástroje, koncové body a oblasti.
• Zachovat matici schopností s úrovní spolehlivosti, nikoli booleovskou.
• Cesta přes zásady nájemce a požadavky na profil modelu, nikoli přímo přes vybraný tajný klíč.
• Ukažte zákazníkům zprávy o selhání pomocí konkrétních kroků k nápravě.
• Naplánujte kontroly stavu a spouštějte opakované kontroly z důvodu chyb běhu.
• Implementujte rotaci jako paralelní ověření následované přepínačem atomového směrování.

Závěr

Nejbezpečnějším procesem registrace BYOK je ověřovatel, nikoli formulář. Zákazníkem dodaný klíč poskytovatele by měl vstoupit do karantény, prokázat svou vazbu, oprávnění, přístup k modelu, signály kvót, chování koncového bodu a limity hlášení a poté by měl být způsobilý pouze pro funkce, které skutečně podporuje.

Praktické doporučení je uložit ověření jako matici schopností, procházet zásadami tenanta a po zahájení produkčního provozu provádět opakované kontroly. Předpověď je přímočará: jak se typy klíčů poskytovatele, ovládací prvky pracovního prostoru, regionální kvóty a oprávnění specifická pro model stále zpřesňují, brány, které považují BYOK za jednorázové tajné nahrání, zaznamenají více selhání produkce, kterým lze předejít. Brány, díky nimž je ověření pověření součástí řídicí roviny, budou zákazníky zpočátku přijímat pomaleji, ale po zahájení provozu s menším počtem překvapení.

Související čtení

• vzor pověření pro oddělení runtime, správce, fakturace a přístupu BYOK