Klucze API AI o zasięgu klienta: izolowanie najemców, budżetów i nadużyć bez bałaganu związanego z kluczami dostawcy

Kiedy produkt pozwala wielu klientom wywoływać modele AI, często kluczem dostawcy wyższego szczebla jest niewłaściwy element podstawowy. Klucz dostawcy zwykle reprezentuje konto, projekt, obszar roboczy lub konto usługi. Twój produkt potrzebuje czegoś węższego: klucza skierowanego do klienta, który identyfikuje jednego najemcę, klienta, aplikację, środowisko, zasady modelu, budżet i regułę audytu.

To jest cel kluczy API AI dostosowanych do klienta. Brama wydaje klucz, uwierzytelnia żądania, stosuje zasady, mierzy wykorzystanie, a następnie wywołuje dostawców nadrzędnych przy użyciu ukrytych poświadczeń. Klienci dalsi nigdy nie otrzymują klucza dostawcy. Otrzymują stałą umowę z Twoją platformą.

Problem z czytnikiem: izolacja klienta bez projektu jednego dostawcy na klienta

Twórcy SaaS, agencje i platformy sprzedawców zazwyczaj muszą odpowiedzieć na praktyczne pytania, zanim będą mogli udostępnić sztuczną inteligencję na dalszym etapie łańcucha dostaw:

• Który klient wygenerował to użycie?
• Która aplikacja, środowisko lub integracja zdecydowała się na ten krok?
• Jakie modele i sposoby są dozwolone?
• Ile ten klient może wydać w tym miesiącu?
• Co się stanie, jeśli klucz wycieknie?
• Czy tego klienta można zawiesić bez wpływu na pozostałych?
• Czy wykorzystanie można później uzgodnić z raportami dostawcy?

Projekty i obszary robocze po stronie dostawcy mogą być pomocne, ale nie zawsze są odpowiednią jednostką dla każdego dalszego klienta. Utworzenie jednej granicy nadrzędnej na klienta może poprawić twardą izolację i raportowanie, ale powoduje również narzut związany z udostępnianiem, fragmentację przydziałów, rozproszenie poświadczeń i więcej pracy związanej z uzgadnianiem.

Klucz wydany przez bramę zapewnia produktowi punkt kontroli na poziomie klienta, nawet w przypadku łączenia poświadczeń nadrzędnych. Obsługuje także silniejsze tryby, takie jak poświadczenia dostawcy powiązanego z dzierżawą lub przyniesienie własnego klucza, gdy klient potrzebuje separacji umownej, granic miejsca zamieszkania lub bezpośredniego posiadania konta dostawcy.

Fakty, rekomendacje i prognozy

Fakty

• Projekty OpenAI obsługują członków, konta usług, klucze API, limity użycia, budżety i zasoby projektowe o określonym zakresie. To sprawia, że projekty są przydatne jako granice wyższego szczebla, ale nie są automatycznie właściwym rozwiązaniem dla każdego klienta końcowego.
• Raporty dotyczące użycia OpenAI mogą grupować wykorzystanie według wymiarów, takich jak projekt, użytkownik, klucz API, model, partia i warstwa usług. Obciążenie zwrotne w ramach SaaS nadal wymaga połączenia rekordów dostawców z identyfikatorami klientów będącymi własnością produktu.
• Antropiczne obszary robocze oddzielają zasoby API według przypadku użycia, zespołu, działu, projektu lub produktu. Klucze API są powiązane z obszarem roboczym, w którym zostały utworzone, i nie można ich przenosić między obszarami roboczymi.
• Antropiczne raportowanie wykorzystania i kosztów obsługuje grupowanie według klucza API, obszaru roboczego, modelu, warstwy usług, okna kontekstu, miejsca przechowywania danych i opcji związanych z szybkością, a koszty są zwracane w dziennych pakietach USD.
• Wskazówki dotyczące kluczy interfejsu API Google Gemini zalecają ograniczenie kluczy, a klucze interfejsu Gemini API są domyślnie ograniczone do interfejsu API języka generatywnego. W zależności od kształtu wdrożenia mogą być dostępne ograniczenia aplikacji, takie jak adresy IP.
• Wytyczne OWASP traktują klucze API jako wymagane kontrole chronionych punktów końcowych i mówią, że klucze powinny zostać unieważnione, gdy klienci naruszają umowy o użytkowaniu.
• Wskazówki dotyczące sekretów OWASP kładą nacisk na najmniejsze uprawnienia, unieważnianie, gdy sekrety nie są już potrzebne lub zostały naruszone, oraz automatyczną rotację w celu ograniczenia błędów implementacji.

Zalecenia

• Używaj kluczy klienta wydanych przez bramę jako uchwytów zasad, a nie tylko tokenów uwierzytelniających.
• Trzymaj dane uwierzytelniające dostawcy wyższego szczebla w ukryciu przed klientami na dalszym etapie.
• Zapisz księgę wykorzystania bramy w momencie żądania, zanim zaczniesz korzystać z pulpitów nawigacyjnych dostawców.
• Wykorzystuj projekty dostawców lub obszary robocze wybiórczo dla klientów wysokiego ryzyka, dużych wolumenów, regulowanych, wrażliwych na miejsce zamieszkania lub klientów odrębnych umową.
• Buduj rotację kluczy jako proces nakładania się, a nie natychmiastowe zdarzenie awarii.

Przewidywania

• Więcej dostawców udostępni bogatsze grupowanie zastosowań i kontrolę budżetu, ale przypisywanie klientów do produktów będzie nadal konieczne na potrzeby rozliczeń SaaS i raportowania sprzedawców.
• Platformy sprzedawców i agencji będą coraz częściej traktować klucze bram jako obiekty komercyjne: powiązane z planami, saldami kredytowymi, zakresami i przepływami pracy pomocy technicznej.
• Klienci mający rygorystyczne wymagania dotyczące zgodności lub zaopatrzenia będą prosić o BYOK lub posiadanie konta dostawcy, podczas gdy większość zwykłych klientów będzie preferować umowę dotyczącą bramy zarządzanej.

Obiekt kluczowy bramy

Klucz o zasięgu klienta powinien zostać przekształcony w ustrukturyzowany obiekt zasad. Modeluj klucz jako coś więcej niż skrót i nazwę.

{
  "key_id": "key_01J9...",
  "ident_dzierżawcy": "dom_dzierżawcy",
  "customer_id": "cust_4812","application_id": "app_support_bot",
  „środowisko”: „produkcja”,
  „właściciel”: {
    "type": "konto_usługi",
    „id”: „svc_support_ai”
  },
  "model_profile_id": "profile_support_standard",
  „allowed_modalities”: [„tekst”, „wejście_obrazu”],
  "tool_policy_id": "tools_readonly_kb",
  "miesięczny_budżet": {
    "waluta": "USD",
    "kwota": "500,00"
  },
  „limity_rate”: {
    „żądania_na_minutę”: 120,
    „input_tokens_per_minutę”: 250000,
    „output_tokens_per_minutę”: 80000
  },
  "retention_policy": "tylko metadane",
  „status”: „aktywny”,
  "created_at": "2026-09-05T10:00:00Z",
  „last_used_at”: null

Dokładne pola będą się różnić, ale zasada nie powinna: każde przychodzące żądanie rozpoznaje klucz w zasadach najemcy przed wysłaniem. Uwierzytelnianie odpowiada na pytanie „kto dzwoni?” Rozwiązanie zasad odpowiada na pytania: „Co może zrobić osoba dzwoniąca, ile może wydać, dokąd może skierować żądanie i co musi zostać zarejestrowane?”

Tutaj także liczy się semantyczna strategia produktu. Platforma sprzedająca AI API dla agencji może wymagać wymiarów klienta i kampanii. Narzędzie programistyczne może wymagać wymiarów obszaru roboczego i repozytorium. Sprzedawca może potrzebować zewnętrznych identyfikatorów klienta pasujących do jego systemu rozliczeniowego.

Przebieg tworzenia klucza

Tworzenie klucza powinno być wystarczająco deterministyczne, aby umożliwić automatyzację i wystarczająco rygorystyczne, aby umożliwić kontrolę bezpieczeństwa.

1. Najpierw utwórz rekord klienta

Nie twórz kluczy osieroconych. Klucz powinien należeć do najemcy i rekordu klienta, zanim istnieje. W przypadku platform sprzedawców rekord klienta powinien zawierać zewnętrzne identyfikatory z systemu CRM lub systemu rozliczeniowego sprzedawcy, metadane planu, grupowanie podatków lub faktur, jeśli to konieczne, oraz pole stanu, w którym można zawiesić wszystkie klucze podrzędne.

2. Dołącz profil modelki

Profil modelu odwzorowuje nazwy modeli skierowanych do klienta na modele i możliwości dostawców. Na przykład standard obsługi może umożliwiać zrównoważony model tekstu, wprowadzanie obrazu i brak wykonywania kodu. research-premium może umożliwiać modele długokontekstowe, wyszukiwanie w Internecie i wyższe pułapy na żądanie.

Nie wymuszaj na dalszych aplikacjach kodowania identyfikatorów modeli dostawców. Użyj profilu bramy, aby zarządzać dostępnością, rezerwami, cenami i wycofywaniem.

3. Ustaw limity wydatków i stawek

Korzystaj jednocześnie z budżetów i limitów stawek. Miesięczny budżet zapobiega zniszczeniu faktur w czasie. Limity szybkości zapobiegają nagłemu nadużyciu, burzom ponownych prób lub przypadkowym pętlom, które mogą pochłonąć cały budżet w ciągu kilku minut.

Przydatne elementy sterujące obejmują:

• Miesięczny budżet klienta.
• Codzienny miękki limit do wykrywania anomalii.
• Współczynnik żądań klucza.
• Współczynnik tokenów wejściowych i wyjściowych.
• Maksymalny szacowany koszt żądania.
• Ograniczenia specyficzne dla narzędzia dotyczące wyszukiwania hostowanego, przetwarzania plików i wykonywania kodu.

Egzekwowanie budżetu powinno zarezerwować szacunkowy koszt przed wysyłką, rozliczyć rzeczywisty koszt po ukończeniu i zwolnić niewykorzystaną rezerwę. Łączy to kluczową politykę z rozliczeniami API AI, zamiast traktować rozliczenia jako opóźnione zadanie raportowania.

4. Wygeneruj i przechowuj sekret poprawnie

Wyświetl jednokrotnie klucz tajny w postaci zwykłego tekstu. Przechowuj tylko silny skrót oraz krótki przedrostek lub odcisk palca w celu wyszukiwania pomocy technicznej. Przedrostek pomaga zespołom wsparcia zidentyfikować „kluczowe zakończenie w 8F2A” bez konieczności dostrzegania tajemnicy.

Typowy wzorzec przechowywania to:

• key_id: stabilny identyfikator bazy danych.
• secret_hash: skrót pełnego sekretu przy użyciu odpowiedniego hasła lub strategii mieszania tokena.
• secret_prefix: krótki, niewrażliwy prefiks wyświetlany.
• odcisk palca: deterministyczny identyfikator wyszukiwania audytowego.
• created_by: użytkownik lub klient Partner API, który utworzył klucz.
• status: aktywny, wyczerpujący, odwołany, poddany kwarantannie, wygasły.

Nigdy nie przechowuj kluczy dostawcy wyższego szczebla w obiekcie klucza klienta. Dane uwierzytelniające dostawcy znajdują się w oddzielnym skarbcu danych uwierzytelniających z własnymi regułami dostępu.

Egzekwowanie czasu żądania

Brama powinna traktować każde wywołanie modelu jako decyzję polityczną, po której następuje wysłanie dostawcy. Praktyczna ścieżka żądania wygląda następująco:

1. Przeanalizuj przedstawiony klucz bramy.
2. Sprawdź skrót i status klucza.
3. Rozwiąż profil najemcy, klienta, aplikacji, środowiska, właściciela i modelu.
4. Sprawdź, czy najemca i klient są aktywni.
5. Zweryfikuj żądany alias modelu, modalność, narzędzia, tryb przechowywania, region i poziom usług.
6. Oszacuj koszt żądania i budżet rezerwowy.
7. Sprawdź limity stawek i progi nadużyć.
8. Wybierz tryb poświadczeń nadrzędnych: zbiorczy, powiązany z dzierżawcą lub BYOK.
9. Wyślij do dostawcy.
10. Przechwytuj wykorzystanie, koszty, referencje dostawców, błędy i sygnały dotyczące bezpieczeństwa.
11. Rozlicz rezerwację budżetu i zapisz końcowe zdarzenie w księdze.

Ta sekwencja sprawia, że brama jest odpowiedzialna za umowę z klientem. Pulpity dostawców stają się danymi wejściowymi do uzgodnienia, a nie jedynym źródłem prawdy.

Wykorzystaj pola księgi użytkowania, które faktycznie przydadzą się później

Księga bramy powinna zawierać wystarczającą ilość szczegółów, aby odpowiedzieć na pytania dotyczące pomocy technicznej, rozliczeń, nadużyć i routingu, bez konieczności domyślnego przechowywania surowych monitów.

Przydatne pola obejmują:

• request_id i trace_id.
• ident_dzierżawy, id_klienta, id_aplikacji i id_klucza.
• Identyfikator użytkownika końcowego, w stosownych przypadkach najlepiej pseudonimowy.
• Alias modelu wymagany przez klienta.
• Rozwiązany dostawca i model wyższego szczebla.
• Wejście, wyjście, rozumowanie, pamięć podręczna, dźwięk, obraz, wideo i użycie narzędzi, jeśli ma to zastosowanie.
• Wyceniony koszt, zarezerwowana kwota, rozliczony koszt, waluta i wersja katalogu cen.
• Identyfikator żądania dostawcy, numer raportu użycia, projekt, obszar roboczy lub wymiar grupowania kluczy API, jeśli jest dostępny.
• Zastosowano zasady przechowywania.
• Kodeksy dotyczące bezpieczeństwa, nadużyć lub decyzji politycznych.
• Kategoria błędu i spróbuj ponownie metadanych.

Ta struktura obsługuje obciążenia zwrotne, obsługę klienta, reakcję na incydenty i przepływ pracy zarządzanie kluczami API, który może odpowiedzieć na pytanie „do czego służy ten klucz?” bez ujawniania niepowiązanych najemców.

Tryby poświadczeń: zbiorcze, powiązane z dzierżawcą i BYOK

Zbiorcze dane uwierzytelniające dostawcy

W trybie domyślnym wiele kluczy klientów przechodzi przez mniejszy zestaw poświadczeń dostawcy. Jest to proste pod względem operacyjnym i ogranicza rozprzestrzenianie się po stronie dostawcy. Działa, gdy brama ma silną atrybucję dzierżawców, egzekwowanie budżetu, ograniczanie szybkości, izolację nadużyć i kontrolę granic pamięci podręcznej.

Kompromis polega na tym, że raporty po stronie dostawcy mogą pokazywać jedynie dane uwierzytelniające bramy lub projekt dostawcy. Musisz połączyć rekordy dostawcy z powrotem z rekordami księgi bramy, aby tworzyć rozliczenia i analizy na poziomie klienta.

Poświadczenia dostawcy powiązanego z dzierżawą

W przypadku większych lub bardziej ryzykownych dzierżawców powiąż dzierżawcę z projektem dedykowanego dostawcy, obszarem roboczym, kontem usługi lub kluczem. Zapewnia to silniejszą separację na poziomie wyższego szczebla i może uprościć raportowanie po stronie dostawcy. Może również zapewnić zabezpieczenie w postaci sztywnych kwot, jeśli dostawca obsługuje limity na tej granicy.

Kosztem jest złożoność operacyjna. Udostępnianie, rotacja, limity dostawców, reakcja na incydenty i uzgadnianie odbywają się teraz w większej liczbie obiektów nadrzędnych.

Przynieś własny klucz

BYOK może być przydatny, gdy klienci muszą być właścicielami konta dostawcy, negocjować własną umowę z dostawcą lub prowadzić oddzielne rozliczenia z dostawcą. Brama nadal, tam gdzie to możliwe, stosuje profile modeli, zasady routingu, analizy i kontrole na poziomie aplikacji.

Kompromisem jest złożoność wsparcia. Konto dostawcy każdego klienta może mieć inny model dostępu, limity, ceny, ustawienia przechowywania i status zdarzenia. Bramka musi wyraźnie wykryć i wyjaśnić te różnice.

Odwołanie i kwarantanna

Odwołanie powinno natychmiast blokować nowe żądania dotyczące klucza klienta bez konieczności rotacji niepowiązanych danych uwierzytelniających dostawcy nadrzędnego. Jest to jedna z głównych zalet kluczy wirtualnych.

Używaj oddzielnych stanów dla różnych działań operacyjnych:

• aktywny: żądania są dozwolone.
• Opróżnianie: stary klucz jest akceptowany podczas okna rotacji, ale emitowane są ostrzeżenia i zdarzenia kontrolne.
• odwołane: nowe prośby są trwale odrzucane.
• poddane kwarantannie: nowe żądania są blokowane z powodu nadużycia, płatności, zasad lub reakcji na incydent.
• wygasł: klucz przekroczył ważność i należy go wymienić.

Kwarantanna powinna być odwracalna po rozwiązaniu incydentu. Cofnięcie zwykle nie powinno być odwracalne, ponieważ przywrócenie starych tajemnic zwiększa zamieszanie i ryzyko.

Gdy klucz narusza zasady użytkowania, zarejestruj przyczynę, podmiot, czas i zakres egzekwowania. Jeśli decyzja została podjęta automatycznie, zachowaj wersję reguły i sygnały, które ją wywołały. Dzięki temu rozmowy z klientami są oparte na faktach.

Rotacja bez przerywania produkcji

Rotacja klawiszy powinna opierać się na procesie nakładania się dwóch klawiszy:

1. Utwórz klucz zastępczy z tym samym klientem, aplikacją, profilem modelu i limitami, chyba że operator zmieni je celowo.
2. Wyświetl raz nowy sekret.
3. Oznacz stary klucz jako wyczerpujący.
4. Zaakceptuj oba klucze przez ograniczony okres, na przykład 7, 14 lub 30 dni, w zależności od planu klienta i ryzyka.
5. Emituj ostrzeżenia o użyciu na klawiszu opróżniania.
6. Powiadom właściciela lub klienta Partner API, gdy w pobliżu upływu terminu stary klucz będzie nadal używany.
7. Unieważnij stary klucz na końcu okna.
8. Zachowaj przypisanie obu kluczowych identyfikatorów w ramach tego samego klienta i aplikacji.

Dzięki temu unika się typowego trybu awarii, w którym poprawa bezpieczeństwa powoduje przerwę w produkcji. Rotacja nadal stanowi kontrolę, ale staje się operacyjnym przepływem pracy z dowodami i terminami.

Powierzchnia API partnera

Jeśli platformy niższego szczebla zarządzają klientami programowo, udostępniaj kluczowe operacje za pośrednictwem interfejsu API partnerów. Interfejs API powinien obsługiwać klucze idempotencji i zdarzenia audytu, ponieważ udostępnianie często odbywa się w ramach przepływów pracy związanych z rozliczeniami, wdrażaniem lub systemem CRM.

Minimalna liczba punktów końcowych:

• POST /customers: utwórz lub dodaj klienta.
• POST /customers/{customer_id}/keys: utwórz klucz.
• GET /customers/{customer_id}/keys: lista kluczy i statusów.
• PATCH /keys/{key_id: aktualizuj zakresy, właściciela, limity, profil modelu lub status.
• POST /keys/{key_id}/rotate: utwórz zamiennik i oznacz stary klucz jako wyczerpujący.
• POST /keys/{key_id}/revoke: natychmiast unieważnij.
• GET /customers/{customer_id}/usage: zwraca wykorzystanie i koszt według zakresu czasu, klucza, aplikacji, modelu lub wymiaru użytkownika końcowego.

Każde żądanie mutacji powinno akceptować klucz idempotencji. Przy każdej zmianie należy zapisać zdarzenie audytu zawierające aktora, cel, pola „przed i po”, źródłowy adres IP lub tożsamość klienta oraz przyczynę, jeśli jest dostępna.

Kiedy używać projektów dostawcy lub obszarów roboczych

Nie traktuj kluczy bramy i granic dostawców jako wzajemnie się wykluczających. Rozwiązują różne problemy.

Użyj kluczy bramy do normalnej kontroli na poziomie klienta:

• Przypisanie według klienta.
• Klucze aplikacji.
• Limity budżetu i stawek.
• Szybkie zawieszenie.
• Przepływy pracy związane z rotacją.
• Analiza użytkowania i raportowanie sprzedawców.

Dodaj projekty dostawców, obszary robocze lub dane uwierzytelniające dedykowanego dostawcy, gdy klient potrzebuje silniejszej separacji:

• Wysoki miesięczny wolumen, który zasługuje na dedykowane przydziały.
• Uregulowane obciążenia z wyraźnymi wymaganiami dotyczącymi miejsca zamieszkania lub przechowywania.
• Umowna separacja faktur.
• Twarde zabezpieczenia budżetowe lub limity po stronie dostawcy.
• Dedykowane monitorowanie nadużyć lub granice przeglądu bezpieczeństwa.
• Konta dostawców należące do klientów za pośrednictwem BYOK.

Praktycznym rozwiązaniem domyślnym jest izolacja wymuszona przez bramę z selektywnymi twardymi granicami nadrzędnymi. Dzięki temu wspólna ścieżka jest prosta, a jednocześnie można zachować ścieżkę eskalacji dla klientów potrzebujących większej separacji.

Lista kontrolna wdrożenia

• Zdefiniuj schemat klucza klienta obejmujący dzierżawcę, klienta, aplikację, środowisko, właściciela, profil modelu, limity, zasady przechowywania i stan.
• Trzymaj sekrety w spoczynku i wyświetlaj zwykły tekst tylko raz.
• Oddziel klucze bramy od magazynu danych uwierzytelniających dostawcy nadrzędnego.
• Przed wysłaniem każde żądanie należy uwzględnić w zasadach.
• Zarezerwuj budżet przed telefonem od dostawcy i rozlicz się, gdy znane będzie ostateczne wykorzystanie.
• Rejestruj użycie z klientem, kluczem, aliasem modelu, modelem wyższego szczebla, kategoriami tokenów, użyciem narzędzi, kosztami podanymi, kosztami ustalonymi i referencjami dostawców.
• Wdrażaj stany aktywne, opróżniane, odwołane, poddane kwarantannie i wygasłe.
• Obsługa nakładania się rotacji dwóch klawiszy.
• Odsłoń operacje interfejsu API partnerów za pomocą kluczy idempotencji.
• Korzystaj z projektów dostawców lub obszarów roboczych tylko wtedy, gdy ich koszt operacyjny jest uzasadniony.

Wnioski, które można zastosować

Izolacja klienta w celu uzyskania dostępu do sztucznej inteligencji powinna zwykle rozpoczynać się od klucza bramy, a nie od klucza dostawcy. Kluczem bramy jest umowa skierowana do klienta: zawiera nazwę dzierżawcy, klienta, aplikacji, profilu modelu, budżetu, limitu stawek, reguły przechowywania i zasad inspekcji. Klucz dostawcy to szczegół implementacji tej umowy.

Ta architektura zapewnia twórcom SaaS i platformom sprzedawców szybkie odwoływanie usług, dokładne przypisanie, budżety na klienta, kontrolowaną rotację i użyteczną analizę wykorzystania bez konieczności tworzenia jednego projektu dostawcy wyższego szczebla dla każdego klienta. Korzystaj z projektów nadrzędnych, obszarów roboczych, poświadczeń powiązanych z dzierżawcą lub BYOK, gdy wymaga tego ryzyko, wolumen, miejsce zamieszkania lub umowa. W przypadku zwykłej ścieżki wymuś izolację klienta w księdze bramy i silniku zasad, a następnie uzgodnij rekordy dostawcy.

Powiązana lektura

• idempotent Partner API udostępnianie klientów, kluczy i kredytów