Klíče rozhraní API AI pro zákazníka: izolujte nájemníky, rozpočty a zneužívání bez rozrůstání klíčů poskytovatelů

Když produkt umožňuje mnoha zákazníkům volat modely umělé inteligence, je často klíčem poskytovatele upstreamu nesprávné primitivum. Klíč poskytovatele obvykle představuje účet, projekt, pracovní prostor nebo účet služby. Váš produkt potřebuje něco užšího: klíč pro zákazníka, který identifikuje jednoho tenanta, zákazníka, aplikaci, prostředí, modelovou politiku, rozpočet a pravidlo auditu.

To je účelem zákaznických klíčů rozhraní AI API. Brána vydá klíč, ověří požadavky, použije zásady, měří využití a poté zavolá poskytovatelům upstream pomocí skrytých přihlašovacích údajů. Následní zákazníci nikdy nedostanou klíč poskytovatele. Dostanou stabilní smlouvu s vaší platformou.

Problém čtenáře: Izolace zákazníka bez jednoho projektu poskytovatele na zákazníka

Tvůrci SaaS, agentury a platformy prodejců obvykle potřebují odpovědět na praktické otázky, než budou moci odhalit přístup k AI:

• Který zákazník vygeneroval toto využití?
• Která aplikace, prostředí nebo integrace provedla hovor?
• Jaké modely a modality jsou povoleny?
• Kolik může tento zákazník utratit tento měsíc?
• Co se stane, když klíč unikne?
• Lze tohoto zákazníka pozastavit, aniž by to ovlivnilo všechny ostatní?
• Lze použití porovnat s hlášeními poskytovatele později?

Projekty a pracovní prostory na straně poskytovatele mohou pomoci, ale nejsou vždy tou správnou jednotkou pro každého následného zákazníka. Vytvoření jedné upstreamové hranice na zákazníka může zlepšit tvrdou izolaci a vykazování, ale také vytváří režii poskytování, fragmentaci kvót, rozrůstání pověření a více práce se sladěním.

Klíč vydaný bránou poskytuje produktu kontrolní bod na úrovni zákazníka, i když jsou sdružená pověření pro odesílání dat. Podporuje také silnější režimy, jako jsou přihlašovací údaje poskytovatele vázané na nájemce nebo přinést svůj vlastní klíč, když zákazník potřebuje smluvní oddělení, hranice trvalého pobytu nebo přímé vlastnictví účtu poskytovatele.

Fakta, doporučení a předpovědi

Fakta

• Projekty OpenAI podporují členy, servisní účty, klíče API, limity využití, rozpočty a zdroje v rámci projektu. Díky tomu jsou projekty užitečné jako upstream hranice, ale ne automaticky to pravé primitivní pro každého koncového zákazníka.
• Přehledy využití OpenAI mohou seskupit využití podle dimenzí, jako je projekt, uživatel, klíč API, model, dávka a úroveň služeb. Zúčtování SaaS stále potřebuje tyto záznamy poskytovatele připojené k identifikátorům zákazníků vlastněných produktem.
• Antropické pracovní prostory oddělují zdroje API podle případu použití, týmu, oddělení, projektu nebo produktu. Klíče API jsou svázány s pracovním prostorem, kde jsou vytvořeny, a nelze je mezi pracovními prostory přesouvat.
• Antropické vykazování využití a nákladů podporuje seskupování podle klíče API, pracovního prostoru, modelu, úrovně služeb, kontextového okna, umístění dat a možností souvisejících s rychlostí, přičemž náklady se vracejí v denních segmentech USD.
• Pokyny pro klíče Google Gemini API doporučují omezit klíče a klíče Gemini API jsou ve výchozím nastavení omezeny na Generative Language API. V závislosti na tvaru nasazení mohou být k dispozici omezení aplikací, jako jsou adresy IP.
• Pokyny OWASP považují klíče API za požadované ovládací prvky pro chráněné koncové body a říkají, že klíče by měly být odvolány, když klienti poruší smlouvy o používání.
• Pokyny týkající se tajných klíčů OWASP kladou důraz na nejmenší oprávnění, zrušení, když tajná tajemství již nejsou vyžadována nebo jsou ohrožena, a na automatickou rotaci, aby se snížila chyba při implementaci.

Doporučení

• Používejte zákaznické klíče vydané bránou jako úchyty zásad, nikoli pouze ověřovací tokeny.
• Uchovávejte přihlašovací údaje poskytovatele upstream skryté před následnými zákazníky.
• Než se budete spoléhat na řídicí panely poskytovatele, zapište si knihu využití brány v okamžiku požadavku.
• Projekty nebo pracovní prostory poskytovatelů používejte selektivně pro vysoce rizikové, objemné, regulované, rezidentní nebo smluvně oddělené zákazníky.
• Vytvářejte rotaci klíčů jako překrývající se pracovní postup, nikoli jako událost okamžitého přerušení.

Předpovědi

• Více poskytovatelů zpřístupní bohatší seskupení využití a řízení rozpočtu, ale pro fakturaci SaaS a přehledy prodejců bude stále nutné přiřazování zákazníků vlastněných produktem.
• Platformy prodejců a agentur budou stále více zacházet s klíči brány jako s komerčními objekty: vázanými na plány, kreditní zůstatky, rozsahy a pracovní postupy podpory.
• Zákazníci s přísným dodržováním předpisů nebo potřebami nákupu požádají o vlastnictví účtu BYOK nebo poskytovatele, zatímco většina běžných zákazníků dá přednost smlouvě se spravovanou bránou.

Objekt klíče brány

Klíč v rozsahu zákazníka by se měl převést na strukturovaný objekt zásad. Minimálně modelujte klíč jako něco víc než hash a název.

{
  "key_id": "key_01J9...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_4812","application_id": "app_support_bot",
  "životní prostředí": "výroba",
  "vlastník": {
    "type": "service_account",
    "id": "svc_support_ai"
  },
  "model_profile_id": "profile_support_standard",
  "allowed_modalities": ["text", "image_input"],
  "tool_policy_id": "tools_readonly_kb",
  "monthly_budget": {
    "currency": "USD",
    "částka": "500,00"
  },
  "rate_limits": {
    "požadavky_za_minutu": 120,
    "input_tokens_per_minute": 250 000,
    "output_tokens_per_minute": 80 000
  },
  "retention_policy": "pouze metadata",
  "status": "aktivní",
  "created_at": "2026-09-05T10:00:00Z",
  "last_used_at": null
}

Přesná pole se budou lišit, ale zásada by se neměla lišit: každý příchozí požadavek převede klíč do zásad tenanta před odesláním. Autentizace odpovídá "kdo volá?" Řešení zásad odpovídá „co může tento volající dělat, kolik může utratit, kam může požadavek směrovat a co musí být zaznamenáno?“

Tady také záleží na sémantické produktové strategii. Platforma prodávající AI API pro agentury může vyžadovat dimenze zákazníka a kampaně. Vývojářský nástroj může potřebovat rozměry pracovního prostoru a úložiště. Prodejce může potřebovat externí ID zákazníků, která odpovídají jeho fakturačnímu systému.

Pracovní postup vytváření klíčů

Vytvoření klíče by mělo být dostatečně deterministické pro automatizaci a dostatečně striktní pro kontrolu zabezpečení.

1. Nejprve vytvořte záznam zákazníka

Nevytvářejte osiřelé klíče. Klíč by měl patřit tenantovi a záznamu zákazníka, než bude existovat. U platforem distributora by měl záznam zákazníka obsahovat externí ID z CRM nebo fakturačního systému prodejce, v případě potřeby metadata plánu, seskupení daní nebo faktur a pole stavu, které může pozastavit všechny podřízené klíče.

2. Připojte profil modelu

Profil modelu mapuje názvy modelů pro zákazníky na modely a možnosti poskytovatelů. Například support-standard může umožnit vyvážený textový model, vkládání obrázků a žádné spouštění kódu. research-premium může umožnit modely s dlouhým kontextem, vyhledávání na webu a vyšší stropy na žádost.

Nevynucujte následné aplikace, aby pevně zakódovaly ID modelu poskytovatele. Použijte profil brány ke správě dostupnosti, záložních reklam, cen a ukončení podpory.

3. Nastavte limity útraty a sazby

Používejte rozpočty a limity sazeb společně. Měsíční rozpočet zabraňuje poškození faktur v průběhu času. Limity sazeb zabraňují tomu, aby náhlé zneužití, opakované bouře nebo náhodné smyčky spotřebovaly celý rozpočet během několika minut.

Mezi užitečné ovládací prvky patří:

• Měsíční zákaznický rozpočet.
• Denní soft cap pro detekci anomálií.
• Míra požadavků na klíč.
• Vstupní a výstupní rychlost tokenů.
• Maximální odhadovaná cena na žádost.
• Omezení konkrétního nástroje pro hostované vyhledávání, zpracování souborů nebo spouštění kódu.

Prosazování rozpočtu by mělo před odesláním rezervovat odhadované náklady, po dokončení uhradit skutečné náklady a uvolnit nevyužitou rezervu. Tím se klíčová zásada propojí s fakturací AI API namísto toho, aby se s fakturací zacházelo jako se zpožděným hlášením.

4. Vytvářejte a ukládejte tajemství správně

Jednou zobrazte tajný kód ve formátu prostého textu. Ukládejte pouze silný hash plus krátkou předponu nebo otisk prstu pro podporu vyhledávání. Předpona pomáhá týmům podpory identifikovat „klíč končící na 8F2A“, aniž by viděli tajemství.

Typický vzor úložiště je:

• id_klíče: identifikátor stabilní databáze.
• secret_hash: hash úplného tajemství pomocí vhodné strategie hašování hesla nebo tokenu.
• secret_prefix: krátká necitlivá předpona zobrazení.
• otisk: deterministický identifikátor pro vyhledávání auditu.
• created_by: uživatel nebo klient Partner API, který vytvořil klíč.
• stav: aktivní, vyprazdňování, odvoláno, v karanténě, vypršela platnost.

Nikdy neukládejte klíče poskytovatele upstream na objekt klíče zákazníka. Pověření poskytovatele patří do samostatného trezoru pověření s vlastními pravidly přístupu.

Vymáhání v době požadavku

Brána by měla s každým voláním modelu zacházet jako s rozhodnutím o zásadách, po kterém následuje odeslání poskytovatele. Praktická cesta požadavku vypadá takto:

1. Analyzujte předložený klíč brány.
2. Vyhledejte klíč hash a stav.
3. Vyřešte profil nájemce, zákazníka, aplikace, prostředí, vlastníka a modelu.
4. Zkontrolujte, zda jsou nájemce a zákazník aktivní.
5. Ověřte požadovaný alias modelu, modalitu, nástroje, režim uchování, oblast a úroveň služeb.
6. Odhadněte náklady na požadavek a rezervní rozpočet.
7. Zkontrolujte limity četnosti a limity zneužití.
8. Vyberte režim přihlašovacích údajů pro odesílání: sdružený, vázaný na tenant nebo BYOK.
9. Odešlete poskytovateli.
10. Zachyťte využití, cenu, reference poskytovatele, chyby a bezpečnostní signály.
11. Vyřešte rozpočtovou rezervaci a zapište poslední událost hlavní knihy.

Tato sekvence udržuje bránu odpovědnou za zákaznickou smlouvu. Panely poskytovatelů se stávají vstupy pro usmíření, nikoli jediným zdrojem pravdy.

Pole v hlavní knize použití, která skutečně pomohou později

Účetní kniha brány by měla uchovat dostatek podrobností, aby mohla odpovídat na otázky týkající se podpory, účtování, zneužívání a směrování, aniž by ve výchozím nastavení vyžadovala nezpracované rychlé úložiště.

Užitečná pole zahrnují:

• request_id a trace_id.
• tenant_id, customer_id, application_id a key_id.
• Identifikátor koncového uživatele, případně pseudonymní.
• Alias modelu požadovaný zákazníkem.
• Vyřešený poskytovatel a model upstreamu.
• Vstup, výstup, uvažování, použití mezipaměti, zvuku, obrázků, videa a nástrojů, kde je to možné.
• Kótovaná cena, rezervovaná částka, zúčtovaná cena, měna a verze katalogu cen.
• ID požadavku poskytovatele, odkaz na přehled využití, projekt, pracovní prostor nebo dimenze seskupení klíčů API, pokud jsou k dispozici.
• Použity zásady uchování.
• Kódy bezpečnosti, zneužití nebo rozhodnutí o zásadách.
• Chyba kategorie a opakujte metadata.

Tato struktura podporuje zpětné zúčtování, zákaznickou podporu, reakce na incidenty a pracovní postup správy klíčů API, který dokáže odpovědět na otázku „co udělal tento klíč?“ aniž byste odhalili nepříbuzné nájemníky.

Režimy pověření: sdružené, vázané na nájemce a BYOK

Pověření sdíleného poskytovatele

Ve výchozím režimu mnoho zákaznických klíčů vede přes menší sadu pověření poskytovatele. To je provozně jednoduché a snižuje to rozrůstání na straně poskytovatelů. Funguje, když má brána silnou atribuci tenantů, vynucování rozpočtu, omezování sazeb, izolaci proti zneužití a kontroly hranic mezipaměti.

Výhodou je, že přehledy na straně poskytovatele mohou zobrazovat pouze přihlašovací údaje brány nebo projekt poskytovatele. Chcete-li vytvářet fakturaci a analýzy na úrovni zákazníka, musíte záznamy poskytovatele připojit zpět k záznamům hlavní knihy brány.

Pověřovací údaje poskytovatele vázaného na tenant

V případě větších nebo rizikovějších tenantů svažte tenanta s projektem vyhrazeného poskytovatele, pracovním prostorem, servisním účtem nebo klíčem. To poskytuje silnější oddělení před vstupem a může zjednodušit podávání zpráv na straně poskytovatele. Může také poskytnout pevnou ochranu kvóty, pokud poskytovatel podporuje limity na této hranici.

Cena je provozní složitost. Zřizování, rotace, limity poskytovatelů, reakce na incidenty a odsouhlasení se nyní odehrávají ve více upstreamových objektech.

Přineste si vlastní klíč

BYOK může být užitečný, když zákazníci musí vlastnit účet poskytovatele, sjednat si vlastní smlouvu s poskytovatelem nebo mít oddělenou fakturaci poskytovatele. Brána stále používá profily modelů, zásady směrování, analýzy a ovládací prvky na úrovni aplikace, kde je to možné.

Komisem je složitost podpory. Účet poskytovatele každého zákazníka může mít jiný model přístupu, kvóty, ceny, nastavení uchovávání a stav incidentu. Brána musí tyto rozdíly detekovat a jasně vysvětlit.

Odvolání a karanténa

Zrušení by mělo okamžitě zablokovat nové požadavky na zákaznický klíč, aniž by bylo nutné střídat nesouvisející přihlašovací údaje poskytovatele. To je jedna z hlavních výhod virtuálních klíčů.

Používejte samostatné stavy pro různé provozní akce:

• aktivní: požadavky jsou povoleny.
• vypouštění: starý klíč je přijat během rotačního okna, ale jsou vydávána varování a události auditu.
• zrušeno: nové požadavky jsou trvale odmítnuty.
• v karanténě: nové požadavky jsou blokovány kvůli zneužití, platbě, zásadám nebo reakci na incident.
• vypršela: klíč překročil svou životnost a musí být vyměněn.

Karanténa by měla být po vyřešení incidentu vratná. Odvolání by obvykle nemělo být vratné, protože obnovení starých tajemství zvyšuje zmatek a riziko.

Když klíč porušuje zásady použití, zaznamenejte důvod, aktéra, čas a rozsah vynucení. Pokud bylo rozhodnutí automatické, zachovejte verzi pravidla a signály, které jej spustily. Díky tomu budou konverzace se zákazníky věcné.

Otáčení bez přerušení výroby

Střídání klíčů by mělo používat pracovní postup překrytí dvou tlačítek:

1. Vytvořte náhradní klíč se stejným zákazníkem, aplikací, modelovým profilem a limity, pokud je operátor záměrně nezmění.
2. Nové tajemství zobrazte jednou.
3. Označte starý klíč jako vypouštění.
4. Přijměte oba klíče na omezenou dobu, například 7, 14 nebo 30 dní v závislosti na plánu a riziku zákazníka.
5. Vysílat upozornění na používání na klíči vypouštění.
6. Upozorněte vlastníka nebo klienta Partner API, když se starý klíč stále používá v blízkosti termínu.
7. Na konci okna zrušte starý klíč.
8. Ponechte atribuci napříč oběma klíčovými ID pod stejným zákazníkem a aplikací.

Vyhnete se tak běžnému režimu selhání, kdy se vylepšení zabezpečení stane výpadkem produkce. Rotace je stále kontrola, ale stává se provozním pracovním postupem s důkazy a termíny.

Partner API Surface

Pokud navazující platformy spravují zákazníky programově, zpřístupněte klíčové operace prostřednictvím Partner API. Rozhraní API by mělo podporovat klíče idempotency a auditní události, protože zřizování často probíhá v rámci pracovních postupů fakturace, registrace nebo CRM.

Minimální koncové body:

• POST /customers: vytvořte nebo upsert zákazníka.
• POST /customers/{customer_id}/keys: vytvořte klíč.
• GET /customers/{customer_id}/keys: seznam klíčů a stavů.
• PATCH /keys/{key_id}: aktualizace rozsahů, vlastníka, limitů, profilu modelu nebo stavu.
• POST /keys/{key_id}/rotate: vytvořte náhradu a označte starý klíč jako vyprazdňující.
• POST /keys/{key_id}/revoke: okamžitě zrušit.
• ZÍSKAT /customers/{customer_id}/usage: návratnost využití a nákladů podle časového rozsahu, klíče, aplikace, modelu nebo dimenze koncového uživatele.

Každý požadavek na mutaci by měl přijmout klíč idempotence. Každá změna by měla napsat událost auditu s aktérem, cílem, poli před a po, zdrojovou IP nebo identitou klienta a důvodem, je-li k dispozici.

Kdy použít projekty poskytovatele nebo pracovní prostory

Nepovažujte klíče brány a hranice poskytovatele za vzájemně se vylučující. Řeší různé problémy.

Pro běžné ovládání na úrovni zákazníka použijte klíče brány:

• Přiřazení podle zákazníka.
• Klíče pro jednotlivé aplikace.
• Rozpočtové a sazbové limity.
• Rychlé pozastavení.
• Pracovní postupy rotace.
• Analytika využití a přehledy distributorů.

Pokud zákazník potřebuje silnější oddělení, přidejte projekty poskytovatele, pracovní prostory nebo pověření vyhrazeného poskytovatele:

• Vysoký měsíční objem, který si zaslouží vyhrazené kvóty.
• Regulovaná pracovní zátěž s explicitními požadavky na bydliště nebo uchování.
• Oddělení smluvní faktury.
• Tvrdé zajištění rozpočtu nebo kvót na straně poskytovatele.
• Vyhrazené hranice sledování zneužití nebo kontroly bezpečnosti.
• Účty poskytovatelů vlastněné zákazníky prostřednictvím BYOK.

Prakticky výchozí je izolace vynucená bránou se selektivními pevnými hranicemi proti proudu. To udržuje společnou cestu jednoduchou a zároveň zachovává cestu eskalace pro zákazníky, kteří potřebují více oddělení.

Kontrolní seznam implementace

• Definujte schéma zákaznických klíčů s tenantem, zákazníkem, aplikací, prostředím, vlastníkem, profilem modelu, limity, zásadami uchovávání a stavem.
• Hashujte tajemství v klidu a zobrazte prostý text pouze jednou.
• Oddělte klíče brány od úložiště přihlašovacích údajů poskytovatele.
• Před odesláním vyřešte každý požadavek na zásady.
• Rezervujte rozpočet před voláním poskytovatele a vyrovnejte jej, až bude známé konečné využití.
• Zaznamenejte použití se zákazníkem, klíčem, aliasem modelu, upstreamovým modelem, kategoriemi tokenů, používáním nástrojů, kótovanými náklady, stanovenými náklady a referencemi poskytovatele.
• Implementujte stavy aktivní, vyčerpávající, odvolané, v karanténě a s vypršenou platností.
• Podporujte překrytí otáčení dvou kláves.
• Vystavte operace Partner API pomocí klíčů idempotency.
• Projekty nebo pracovní prostory poskytovatelů používejte pouze tam, kde jsou jejich provozní náklady odůvodněné.

Aplikovatelný závěr

Izolace zákazníků pro přístup AI by měla obvykle začínat klíčem brány, nikoli klíčem poskytovatele. Klíčem brány je smlouva pro zákazníka: jmenuje nájemce, zákazníka, aplikaci, profil modelu, rozpočet, limit sazby, pravidlo uchování a zásady auditu. Klíč poskytovatele je detail implementace za touto smlouvou.

Tato architektura poskytuje tvůrcům SaaS a platformám prodejců rychlé odvolání, přesnou atribuci, rozpočty na zákazníka, řízenou rotaci a užitečnou analýzu využití, aniž by ve výchozím nastavení vytvořili jeden projekt poskytovatele upstream pro každého zákazníka. Použijte upstream projekty, pracovní prostory, pověření vázaná na tenanta nebo BYOK, pokud to riziko, objem, bydliště nebo smlouva vyžaduje. Pro běžnou cestu vynucte izolaci zákazníků v knize brány a modulu zásad a poté srovnejte záznamy poskytovatele.

Související informace

• idempotent API kredity