Kľúče rozhrania API AI na úrovni zákazníka: izolujte nájomníkov, rozpočty a zneužívanie bez rozšírenia kľúča poskytovateľa

Keď produkt umožňuje mnohým zákazníkom volať modely AI, kľúčom poskytovateľa upstreamu je často nesprávne primitívum. Kľúč poskytovateľa zvyčajne predstavuje účet, projekt, pracovný priestor alebo účet služby. Váš produkt potrebuje niečo užšie: kľúč pre zákazníka, ktorý identifikuje jedného nájomníka, zákazníka, aplikáciu, prostredie, modelovú politiku, rozpočet a pravidlo auditu.

To je účel kľúčov rozhrania API AI pre zákazníka. Brána vydá kľúč, overí požiadavky, aplikuje politiku, meria využitie a potom zavolá poskytovateľom upstream pomocou skrytých poverení. Následní zákazníci nikdy nedostanú kľúč poskytovateľa. Dostanú stabilnú zmluvu s vašou platformou.

Problém s čítačkou: Izolácia zákazníka bez jedného projektu poskytovateľa na zákazníka

Tvorcovia SaaS, agentúry a platformy predajcov zvyčajne potrebujú odpovedať na praktické otázky predtým, ako môžu odhaliť prístup AI nadol:

• Ktorý zákazník vygeneroval toto použitie?
• Ktorá aplikácia, prostredie alebo integrácia uskutočnila hovor?
• Ktoré modely a spôsoby sú povolené?
• Koľko môže tento zákazník minúť tento mesiac?
• Čo sa stane, ak dôjde k úniku kľúča?
• Je možné tohto zákazníka pozastaviť bez toho, aby to ovplyvnilo všetkých ostatných?
• Je možné použitie porovnať s prehľadmi poskytovateľa neskôr?

Projekty a pracovné priestory na strane poskytovateľa môžu pomôcť, no nie sú vždy tou správnou jednotkou pre každého následného zákazníka. Vytvorenie jednej upstreamovej hranice na zákazníka môže zlepšiť tvrdú izoláciu a vykazovanie, ale tiež vytvára režijné náklady na poskytovanie, fragmentáciu kvót, rozširovanie poverení a viac práce na zosúlaďovaní.

Kľúč vydaný bránou poskytuje produktu kontrolný bod na úrovni zákazníka, a to aj v prípade, že sú združené upstream poverenia. Podporuje tiež silnejšie režimy, ako sú napríklad poverenia poskytovateľa viazané na nájomcu alebo prinesenie vlastného kľúča, keď zákazník potrebuje zmluvné oddelenie, hranice bydliska alebo priame vlastníctvo účtu poskytovateľa.

Fakty, odporúčania a predpovede

Fakty

• Projekty OpenAI podporujú členov, servisné účty, kľúče API, limity používania, rozpočty a rozsah zdrojov projektu. Vďaka tomu sú projekty užitočné ako upstream hranice, ale nie sú automaticky tým správnym primitívom pre každého koncového zákazníka.
• Prehľady používania OpenAI môžu zoskupovať využitie podľa dimenzií, ako je projekt, používateľ, kľúč API, model, dávka a úroveň služieb. Spätná platba SaaS stále potrebuje tieto záznamy poskytovateľa spojené s identifikátormi zákazníkov vlastnených produktom.
• Antropické pracovné priestory oddeľujú zdroje API podľa prípadu použitia, tímu, oddelenia, projektu alebo produktu. Kľúče API sú prepojené s pracovným priestorom, kde sú vytvorené, a nemožno ich presúvať medzi pracovnými priestormi.
• Antropické vykazovanie využívania a nákladov podporuje zoskupovanie podľa kľúča API, pracovného priestoru, modelu, úrovne služieb, kontextového okna, umiestnenia údajov a možností súvisiacich s rýchlosťou, pričom náklady sa vracajú v denných segmentoch USD.
• Pokyny pre kľúče rozhrania Google Gemini API odporúčajú obmedziť kľúče a kľúče rozhrania Gemini API sú predvolene obmedzené na rozhranie Generative Language API. Obmedzenia aplikácií, ako sú adresy IP, môžu byť dostupné v závislosti od tvaru nasadenia.
• Pokyny OWASP považujú kľúče API za požadované ovládacie prvky pre chránené koncové body a hovoria, že kľúče by sa mali odvolať, keď klienti porušia zmluvy o používaní.
• Pokyny týkajúce sa tajomstiev OWASP kladú dôraz na najmenšie privilégiá, zrušenie, keď už tajomstvá nie sú potrebné alebo sú ohrozené, a automatické striedanie na zníženie chýb pri implementácii.

Odporúčania

• Používajte zákaznícke kľúče vydané bránou ako rukoväte pravidiel, nielen autentifikačné tokeny.
• Uchovajte poverenia poskytovateľa upstream skryté pred následnými zákazníkmi.
• Napíšte knihu používania brány v čase vyžiadania, skôr než sa spoľahnete na informačné panely poskytovateľa.
• Projekty poskytovateľov alebo pracovné priestory používajte selektívne pre vysokorizikových zákazníkov, zákazníkov s veľkým objemom, regulovaných zákazníkov, ktorí sú citliví na bydlisko, alebo zmluvne oddelených zákazníkov.
• Vytvorte striedanie kľúčov ako prekrývajúci sa pracovný postup, nie ako udalosť okamžitého zlyhania.

Predpovede

• Viac poskytovateľov odkryje bohatšie zoskupovanie používania a riadenie rozpočtu, ale pripisovanie zákazníkov vlastnených produktom bude stále potrebné pre fakturáciu SaaS a prehľady predajcov.
• Platformy predajcov a agentúr budú čoraz viac považovať kľúče brán za komerčné objekty: spojené s plánmi, kreditnými zostatkami, rozsahmi a podpornými pracovnými postupmi.
• Zákazníci s prísnymi požiadavkami na súlad alebo obstarávanie budú požadovať vlastníctvo účtu BYOK alebo poskytovateľa, zatiaľ čo väčšina bežných zákazníkov uprednostňuje zmluvu o riadenej bráne.

Objekt kľúča brány

Kľúč s rozsahom pre zákazníka by mal viesť k štruktúrovanému objektu politiky. Minimálne modelujte kľúč ako niečo viac než len hash a názov.

{
  "key_id": "key_01J9...",
  "tenant_id": "tenant_acme",
  "customer_id": "cust_4812","application_id": "app_support_bot",
  "životné prostredie": "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",
    "suma": "500,00"
  },
  "rate_limits": {
    "requests_per_minute": 120,
    "input_tokens_per_minute": 250 000,
    "output_tokens_per_minute": 80 000
  },
  "retention_policy": "iba metaúdaje",
  "status": "aktívny",
  "created_at": "2026-09-05T10:00:00Z",
  "last_used_at": null
}

Presné polia sa budú líšiť, ale zásada by sa nemala líšiť: každá prichádzajúca požiadavka pred odoslaním rozdelí kľúč do politiky nájomníka. Autentifikácia odpovedá „kto volá?“ Rezolúcia pravidiel odpovedá „čo môže tento volajúci robiť, koľko môže minúť, kam môže smerovať žiadosť a čo musí byť zaznamenané?“

Aj tu je dôležitá sémantická produktová stratégia. Platforma predávajúca AI API pre agentúry môže potrebovať dimenzie zákazníka a kampane. Vývojársky nástroj môže potrebovať rozmery pracovného priestoru a úložiska. Predajca môže potrebovať externé ID zákazníkov, ktoré sa zhodujú s jeho fakturačným systémom.

Pracovný postup vytvorenia kľúča

Vytvorenie kľúča by malo byť dostatočne deterministické na automatizáciu a dostatočne prísne na kontrolu zabezpečenia.

1. Najprv vytvorte záznam zákazníka

Nevytvárajte osirotené kľúče. Kľúč by mal patriť nájomníkovi a záznamu o zákazníkovi skôr, ako bude existovať. V prípade platforiem predajcu by záznam o zákazníkovi mal obsahovať externé ID z CRM alebo fakturačného systému predajcu, v prípade potreby metadáta plánu, zoskupovanie daní alebo faktúr a pole stavu, ktoré môže pozastaviť všetky podradené kľúče.

2. Pripojte profil modelu

Profil modelu mapuje názvy modelov pre zákazníkov na modely a možnosti poskytovateľov. Napríklad support-standard môže umožniť vyvážený textový model, zadávanie obrázkov a žiadne spustenie kódu. research-premium môže umožniť modely s dlhým kontextom, vyhľadávanie na webe a vyššie stropy na žiadosť.

Nevynucujte následné aplikácie, aby pevne zakódovali ID modelu poskytovateľa. Použite profil brány na spravovanie dostupnosti, záložných zdrojov, cien a ukončenia podpory.

3. Nastavte limity výdavkov a sadzieb

Rozpočty a limity sadzieb používajte súčasne. Mesačný rozpočet zabraňuje poškodeniu faktúr v priebehu času. Limity sadzieb zabraňujú náhlemu zneužitiu, opakovaným búrkam alebo náhodným slučkám spotrebovať celý rozpočet v priebehu niekoľkých minút.

Užitočné ovládacie prvky zahŕňajú:

• Mesačný zákaznícky rozpočet.
• Denné mäkké viečko na detekciu anomálií.
• Pomer požiadaviek na kľúč.
• Rýchlosť tokenov vstupu a výstupu.
• Maximálne odhadované náklady na žiadosť.
• Obmedzenia špecifické pre nástroj pre hostené vyhľadávanie, spracovanie súborov alebo spustenie kódu.

Presadzovanie rozpočtu by malo rezervovať odhadované náklady pred odoslaním, uhradiť skutočné náklady po dokončení a uvoľniť nevyužitú rezervu. Toto spája kľúčové pravidlo s fakturáciou AI API namiesto toho, aby sa fakturácia považovala za úlohu s oneskoreným prehľadom.

4. Správne vygenerujte a uložte tajomstvo

Jedenkrát zobrazte tajný kód vo forme čistého textu. Uložte iba silný hash plus krátku predponu alebo odtlačok prsta na vyhľadanie podpory. Predpona pomáha tímom podpory identifikovať „kľúč končiaci na 8F2A“ bez toho, aby videli tajomstvo.

Typický spôsob ukladania je:

• key_id: identifikátor stabilnej databázy.
• secret_hash: hash úplného tajomstva pomocou vhodného hesla alebo stratégie hašovania tokenov.
• tajná_predpona: krátka necitlivá predpona zobrazenia.
• odtlačok prsta: deterministický identifikátor pre vyhľadávanie auditu.
• created_by: používateľ alebo klient rozhrania Partner API, ktorý vytvoril kľúč.
• stav: aktívny, vyčerpaný, odvolaný, v karanténe, platnosť vypršala.

Nikdy neukladajte kľúče poskytovateľa upstream na objekt kľúča zákazníka. Poverenia poskytovateľa patria do samostatného trezoru poverení s vlastnými pravidlami prístupu.

Vymáhanie v čase žiadosti

Brána by mala považovať každé volanie modelu za rozhodnutie o politike, po ktorom nasleduje odoslanie poskytovateľa. Praktická cesta žiadosti vyzerá takto:

1. Analyzujte prezentovaný kľúč brány.
2. Vyhľadajte kľúč hash a stav.
3. Vyriešte profil nájomníka, zákazníka, aplikácie, prostredia, vlastníka a modelu.
4. Skontrolujte, či sú nájomník a zákazník aktívni.
5. Overte požadovaný alias modelu, modalitu, nástroje, režim uchovávania, región a úroveň služieb.
6. Odhadnite náklady na žiadosť a rezervný rozpočet.
7. Skontrolujte limity frekvencie a limity zneužitia.
8. Vyberte režim poverení pre odosielanie: združený, viazaný na nájomníka alebo BYOK.
9. Odoslanie poskytovateľovi.
10. Zaznamenajte spotrebu, cenu, referencie poskytovateľa, chyby a bezpečnostné signály.
11. Urovnajte rezerváciu rozpočtu a zapíšte poslednú udalosť účtovnej knihy.

Táto postupnosť ponecháva bránu zodpovednú za zákaznícku zmluvu. Panely poskytovateľov sa stávajú vstupmi na zmierenie, nie jediným zdrojom pravdy.

Polia v knihe použitia, ktoré skutočne pomôžu neskôr

Účtovná kniha brány by mala uchovávať dostatok podrobností, aby mohla odpovedať na otázky týkajúce sa podpory, fakturácie, zneužívania a smerovania bez toho, aby v predvolenom nastavení vyžadovala nespracované rýchle úložisko.

Užitočné polia zahŕňajú:

• request_id a trace_id.
• tenant_id, customer_id, application_id a key_id.
• Identifikátor koncového používateľa, v prípade potreby prednostne pseudonymný.
• Alias modelu požadovaný zákazníkom.
• Vyriešený poskytovateľ upstream a model.
• Vstup, výstup, uvažovanie, použitie vo vyrovnávacej pamäti, zvuk, obrázok, video a prípadne použitie nástrojov.
• Kótovaná cena, rezervovaná suma, zúčtovaná cena, mena a verzia katalógu cien.
• ID požiadavky poskytovateľa, referencia správy o používaní, projekt, pracovný priestor alebo dimenzia zoskupenia kľúčov API, ak sú k dispozícii.
• Použili sa pravidlá uchovávania.
• Kódy bezpečnosti, zneužívania alebo rozhodovania o pravidlách.
• Chybná kategória a skúste metadáta znova.

Táto štruktúra podporuje kompenzáciu, zákaznícku podporu, reakciu na incidenty a pracovný postup správy kľúčov API, ktorý dokáže odpovedať na otázku, čo urobil tento kľúč? bez odhalenia nesúvisiacich nájomníkov.

Režimy poverení: združený, viazaný nájomníkom a BYOK

Združené poverenia poskytovateľa

V predvolenom režime vedie veľa zákazníckych kľúčov cez menšiu skupinu poverení poskytovateľa. Je to prevádzkovo jednoduché a znižuje to rozrastanie na strane poskytovateľa. Funguje, keď má brána silné priradenie nájomníkov, presadzovanie rozpočtu, obmedzovanie sadzieb, izoláciu zneužitia a ovládacie prvky na hranici vyrovnávacej pamäte.

Výhodou je, že prehľady na strane poskytovateľa môžu zobrazovať iba poverenia brány alebo projekt poskytovateľa. Musíte pripojiť záznamy poskytovateľa späť k záznamom hlavnej knihy, aby ste mohli vytvárať fakturáciu a analýzy na úrovni zákazníka.

Poverenia poskytovateľa viazané na nájomcu

V prípade väčších alebo rizikovejších nájomníkov pripojte nájomníka k vyhradenému projektu poskytovateľa, pracovnému priestoru, účtu služby alebo kľúču. To poskytuje silnejšie oddelenie od začiatku a môže zjednodušiť podávanie správ na strane poskytovateľa. Môže tiež poskytnúť pevnú ochranu kvóty, ak poskytovateľ podporuje limity na tejto hranici.

Cena je prevádzková zložitosť. Poskytovanie, rotácia, limity poskytovateľov, odozva na incidenty a zosúlaďovanie sa teraz uskutočňujú vo viacerých objektoch proti prúdu.

Prineste si vlastný kľúč

BYOK môže byť užitočný, keď zákazníci musia vlastniť účet poskytovateľa, dohodnúť si zmluvu s vlastným poskytovateľom alebo mať oddelenú fakturáciu poskytovateľa. Brána stále používa profily modelov, politiku smerovania, analýzy a ovládacie prvky na úrovni aplikácie tam, kde je to možné.

Komisom je zložitosť podpory. Účet poskytovateľa každého zákazníka môže mať odlišný prístup k modelu, kvóty, ceny, nastavenia uchovávania a stav incidentu. Brána musí tieto rozdiely odhaliť a jasne vysvetliť.

Odvolanie a karanténa

Zrušenie by malo okamžite zablokovať nové požiadavky na zákaznícky kľúč bez rotácie nesúvisiacich poverení poskytovateľa. Toto je jedna z hlavných výhod virtuálnych kľúčov.

Použite samostatné stavy pre rôzne prevádzkové akcie:

• aktívne: požiadavky sú povolené.
• vypúšťanie: starý kľúč je akceptovaný počas obdobia rotácie, ale vydávajú sa upozornenia a udalosti auditu.
• odvolané: nové žiadosti budú natrvalo odmietnuté.
• v karanténe: nové žiadosti sú zablokované z dôvodu zneužitia, platby, pravidiel alebo reakcie na incident.
• platnosť vypršala: kľúč prekročil svoju životnosť a je potrebné ho vymeniť.

Karanténa by mala byť po vyriešení incidentu reverzibilná. Odvolanie by zvyčajne nemalo byť reverzibilné, pretože obnovenie starých tajomstiev zvyšuje zmätok a riziko.

Keď kľúč porušuje pravidlá používania, zaznamenajte dôvod, aktéra, čas a rozsah presadzovania. Ak bolo rozhodnutie automatizované, zachovajte verziu pravidla a signály, ktoré ho spustili. Vďaka tomu budú konverzácie so zákazníkmi vecné.

Rotácia bez prerušenia výroby

Striedanie kľúčov by malo používať pracovný postup prekrývania dvoch tlačidiel:

1. Vytvorte náhradný kľúč s rovnakým zákazníkom, aplikáciou, modelovým profilom a limitmi, pokiaľ ich operátor nezmení úmyselne.
2. Nové tajomstvo zobrazte raz.
3. Označte starý kľúč ako vypúšťanie.
4. Akceptujte oba kľúče na obmedzené obdobie, napríklad 7, 14 alebo 30 dní v závislosti od plánu a rizika zákazníka.
5. Vyslať upozornenia na používanie na kľúči vypúšťania.
6. Upovedomte vlastníka alebo klienta Partner API, keď sa starý kľúč stále používa blízko termínu.
7. Odvolajte starý kľúč na konci okna.
8. Ponechajte priradenie medzi oboma kľúčovými ID pod rovnakým zákazníkom a aplikáciou.

Vyhnete sa tak bežnému režimu zlyhania, kedy sa zlepšenie zabezpečenia stane výpadkom produkcie. Rotácia je stále kontrola, ale stáva sa prevádzkovým pracovným tokom s dôkazmi a termínmi.

Partner API Surface

Ak nadväzujúce platformy spravujú zákazníkov programovo, odhaľte kľúčové operácie prostredníctvom rozhrania API partnera. Rozhranie API by malo podporovať kľúče idempotencie a udalosti auditu, pretože poskytovanie sa často deje v rámci pracovných postupov fakturácie, registrácie alebo CRM.

Minimálne koncové body:

• POST /customers: vytvorenie alebo rozšírenie zákazníka.
• POST /customers/{customer_id}/keys: vytvorte kľúč.
• GET /customers/{customer_id}/keys: zoznam kľúčov a stavov.
• PATCH /keys/{key_id}: aktualizujte rozsahy, vlastníka, limity, profil modelu alebo stav.
• POST /keys/{key_id}/rotate: vytvorte náhradu a označte starý kľúč ako vyčerpaný.
• POST /keys/{key_id}/revoke: okamžite zrušiť.
• GET /customers/{customer_id}/usage: návratnosť spotreby a nákladov podľa časového rozsahu, kľúča, aplikácie, modelu alebo dimenzie koncového používateľa.

Každá žiadosť o zmenu by mala akceptovať kľúč idempotencie. Každá zmena by mala napísať udalosť auditu s aktérom, cieľom, poliami pred a po, zdrojovou IP alebo identitou klienta a dôvodom, ak je k dispozícii.

Kedy použiť projekty poskytovateľa alebo pracovné priestory

Kľúče brány a hranice poskytovateľa nepovažujte za vzájomne sa vylučujúce. Riešia rôzne problémy.

Na bežné ovládanie na úrovni zákazníka použite kľúče brány:

• Priradenie podľa zákazníka.
• Kľúče pre jednotlivé aplikácie.
• Obmedzenia rozpočtu a sadzby.
• Rýchle pozastavenie.
• Pracovné postupy rotácie.
• Analýza používania a prehľady predajcov.

Pridajte projekty poskytovateľa, pracovné priestory alebo poverenia špecializovaného poskytovateľa, keď zákazník potrebuje silnejšie oddelenie:

• Vysoký mesačný objem, ktorý si zaslúži vyhradené kvóty.
• Regulované pracovné zaťaženie s explicitnými požiadavkami na pobyt alebo uchovávanie.
• Zmluvné oddelenie faktúr.
• Pevné zabezpečenie rozpočtu alebo kvót na strane poskytovateľa.
• Vyhradené hranice monitorovania zneužívania alebo kontroly bezpečnosti.
• Účty poskytovateľa vo vlastníctve zákazníka prostredníctvom BYOK.

Praktické predvolené nastavenie je izolácia vynútená bránou so selektívnymi pevnými hranicami proti prúdu. Vďaka tomu je spoločná cesta jednoduchá a zároveň sa zachová cesta eskalácie pre zákazníkov, ktorí potrebujú viac oddelenia.

Kontrolný zoznam implementácie

• Definujte schému kľúča zákazníka s nájomníkom, zákazníkom, aplikáciou, prostredím, vlastníkom, profilom modelu, limitmi, politikou uchovávania a stavom.
• Hashujte tajomstvá v pokoji a zobrazte čistý text iba raz.
• Oddeľte kľúče brány od ukladacieho priestoru poverení poskytovateľa.
• Pred odoslaním vyriešte každú požiadavku na pravidlá.
• Zarezervujte si rozpočet pred hovorom poskytovateľa a vyrovnajte ho, keď bude známe konečné využitie.
• Zaznamenajte používanie so zákazníkom, kľúčom, aliasom modelu, modelom upstream, kategóriami tokenov, používaním nástrojov, kótovanými nákladmi, vyrovnanými nákladmi a referenciami poskytovateľa.
• Implementujte aktívne stavy, stavy vyčerpania, odvolania, karantény a stavy s vypršanou platnosťou.
• Podpora prekrytia otáčania dvoch klávesov.
• Odhaľte operácie rozhrania API partnera pomocou kľúčov idempotencie.
• Projekty poskytovateľov alebo pracovné priestory používajte iba vtedy, ak sú ich prevádzkové náklady opodstatnené.

Uplatniteľný záver

Izolácia zákazníka pre prístup AI by sa mala zvyčajne začínať kľúčom brány, nie kľúčom poskytovateľa. Kľúčom brány je zmluva pre zákazníka: pomenúva nájomcu, zákazníka, aplikáciu, profil modelu, rozpočet, limit sadzby, pravidlo uchovávania a politiku auditu. Kľúč poskytovateľa je detail implementácie tejto zmluvy.

Táto architektúra poskytuje tvorcom SaaS a platformám predajcov rýchle zrušenie, presné pripisovanie, rozpočty na zákazníka, riadenú rotáciu a užitočnú analýzu používania bez toho, aby sa v predvolenom nastavení vytvoril jeden projekt poskytovateľa pre každého zákazníka. Použite upstream projekty, pracovné priestory, poverenia viazané na nájomcu alebo BYOK, keď si to vyžaduje riziko, objem, sídlo alebo zmluva. Pre bežnú cestu presadzujte izoláciu zákazníkov v účtovnej knihe brány a nástroji politiky a potom zosúlaďte záznamy poskytovateľa.

Súvisiace čítanie

• idempotent API, kľúče a kľúče API kredity