Kontrola agentów: klucze z zakresami, limity wydatków i bezpieczne ponowne próby
Agent, który wysyła wiadomości przez Bird, ma poświadczenie i wydaje Twoje saldo. To, co może zrobić, ogranicza pięć mechanizmów kontroli. Pierwszym jest samo poświadczenie. Pozostałe cztery działają tylko wtedy, gdy poświadczenie agenta nie pozwala ich zmienić, więc zacznij od poświadczenia.
| Mechanizm kontroli | Co ogranicza | Co otrzymuje wywołujący po osiągnięciu limitu | Kto go ustawia |
|---|---|---|---|
| Poświadczenie | Operacje, które agent może wywołać | 403 | Osoba, która tworzy klucz lub zatwierdza logowanie |
| Klucz idempotencji | Zduplikowane wysyłki przy ponownej próbie żądania | Pierwotna odpowiedź, odtworzona ponownie | Wywołujący, przy każdym żądaniu |
| Lista dozwolonych krajów docelowych SMS | Kraje, do których może trafić wysyłka SMS API | 422 SMSDestinationNotEnabled | Poświadczenie z uprawnieniem zapisu sms_management |
| Dzienny limit wydatków SMS | Wydatki SMS na jeden kraj w ciągu dnia | 422 SMSDestinationDailySpendExceeded | Poświadczenie z uprawnieniem zapisu sms_management |
| Portfel przedpłacony | Wydatki w modelu pay-as-you-go | 402 dla SMS i WhatsApp. Płatny e-mail jest obciążany po wysłaniu. | Właściciel organizacji lub administrator rozliczeń |
Lista dozwolonych miejsc docelowych i dzienny limit wydatków opisane na tej stronie dotyczą SMS. Verify i Voice mają własne ustawienia miejsc docelowych, a ich stan początkowy jest inny. E-mail i WhatsApp nie mają listy dozwolonych miejsc docelowych ani dziennego limitu wydatków, więc tam agenta ograniczają zakresy poświadczenia i portfel.
Wybierz poświadczenie, którego używa agent
Agent wywołuje Bird za pomocą jednego z dwóch rodzajów poświadczeń. Różnią się one zasięgiem uprawnień.
- Klucz API (
bk_) ma zakresy, które mu nadasz, i należy do jednego obszaru roboczego. Nie może wystawić innego klucza ani uzyskać dostępu do rozliczeń, członków ani ustawień organizacji. Twój kod wysyła go jako token bearer. CLI i lokalny serwer MCP (bird mcp) używają klucza zBIRD_API_KEY, jeśli jest ustawiony, zamiast zapisanego logowania. - Token OAuth (
bt_) to poświadczenie, które CLI i serwer MCP otrzymują po zalogowaniu się osoby. Ma uprawnienia zatwierdzone przez tę osobę i nigdy więcej, niż ona sama posiada. Mogą one obejmować zapisapi_keys, zapissms_managementi rozliczenia organizacji. Agent z takim tokenem może wystawiać klucze, włączać kraje i podnosić limity opisane na tej stronie.
Zakres możliwości tokenu OAuth zależy od sposobu jego utworzenia:
bird auth loginprosi o dostęp tylko do odczytu.--scopeprosi o wskazany przez Ciebie zestaw, a--yoloo wszystkie uprawnienia, które możesz delegować. Wynik zatwierdzasz w przeglądarce.- Hostowany klient MCP może prosić o wszystkie uprawnienia, które możesz delegować. Na ekranie zgody wybierasz, które z nich przyznać. Przed zatwierdzeniem odznacz te, których agent nie potrzebuje.
- Samodzielna rejestracja nie ma ekranu zgody. Tworzone przez nią poświadczenie ma wszystkie uprawnienia, które może delegować właściciel nowej organizacji, w tym uprawnienia do rozliczeń organizacji.
Dla agenta działającego bez nadzoru utwórz klucz API o ograniczonym zakresie i przekaż agentowi ten klucz. Szersze logowanie zostaw osobie, która konfiguruje obszar roboczy. Logowanie narzędzia możesz odwołać w Profile > Connected apps. Strona Klucze API i tokeny OAuth porównuje oba rodzaje poświadczeń.
Ogranicz zakres każdego klucza do potrzebnych produktów
Klucz API ma listę zakresów, z których każdy obejmuje obszar produktu na poziomie read lub write. Klucz, który tylko wysyła SMS, ma sms:write. Żądanie spoza zakresów klucza zwraca 403, więc klucz, który wyciekł lub jest nadużywany, sięga tylko tego, co mu przyznano.
Trzy właściwości klucza obowiązują niezależnie od jego zakresów:
- Klucz nie może wystawić innego klucza. Wystawianie i rotacja kluczy wymagają
api_keys:write, które nie jest dostępne dla kluczy API. Zatwierdza to osoba w sesji panelu albo przy logowaniu przez CLI lub MCP. - Klucz działa tylko w swoim obszarze roboczym. Nie ma dostępu do rozliczeń, członków organizacji ani ustawień organizacji.
- Klucz może wygasnąć. Ustaw
expires_atprzy jego tworzeniu, a po tym momencie klucz będzie zwracać401. Klucz możesz w każdej chwili zrotować lub odwołać.
Utwórz klucz w panelu albo z terminala. Logowanie CLI może nadać kluczowi tylko te zakresy, które samo ma, dlatego to polecenie prosi o sms:write oraz api_keys:write:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeStrona Uwierzytelnianie i klucze API zawiera tabelę zakresów i opisuje wygasanie, rotację oraz odwoływanie kluczy.
Spróbuj ponownie wysłać wiadomość bez podwójnej wysyłki
Agent, który nie otrzymał odpowiedzi, nie wie, czy jego żądanie zostało przyjęte. Wysyłaj nagłówek Idempotency-Key z unikalną wartością dla każdej zamierzonej wysyłki, a gdy wynik jest nieznany, powtórz to samo żądanie z tym samym kluczem. Bird zwraca pierwotną odpowiedź i przyjmuje wiadomość tylko raz. Odtworzona odpowiedź zawiera Idempotency-Replay: true.
Gwarancja obejmuje jedną zaakceptowaną operację na klucz w okresie przechowywania. Dotyczy akceptacji przez API. Doręczenie na telefon jest raportowane osobno, przez status wiadomości i jej zdarzenia.
SDK generują klucz dla każdego wywołania modyfikującego i używają go ponownie przy automatycznych ponownych próbach. W CLI przekaż --idempotency-key. Idempotentność opisuje format klucza, okres przechowywania oraz to, co się dzieje, gdy klucz zostanie użyty ponownie z innym żądaniem.
Zezwól na każdy kraj docelowy SMS
Lista dozwolonych krajów docelowych SMS domyślnie blokuje wszystko. Wysyłka przez SMS API trafia do kraju włączonego na liście albo zostaje odrzucona z 422 SMSDestinationNotEnabled, zanim zostanie ustalony nadawca, więc żadna wiadomość nie zostaje zaakceptowana. Agent skierowany do nieoczekiwanego kraju dostaje odmowę. Dotyczy to wysyłki z Twojego kodu, z bird sms send oraz z narzędzia sms_send MCP.
Kody weryfikacyjne nie korzystają z tej listy. Verify ma własną listę w sekcji Verify destinations, gdzie każdy kraj jest domyślnie włączony. Poświadczenie z uprawnieniem zapisu verify może więc wysłać kod przez SMS do kraju zablokowanego na tej liście. Jeśli agent ma verify, wyłącz na tamtej stronie również kraje, których nie obsługujesz.
Włącz kraj w sekcji SMS > Destinations, za pomocą bird sms destinations update lub narzędzia sms_destinations_update MCP:
bird sms destinations update --destination NL=trueZmiana listy dozwolonych krajów wymaga zakresu sms_management na poziomie write. Poświadczenie mające tylko sms może wysyłać do włączonych krajów, ale nie może włączać kolejnych. Daj agentowi wysyłającemu sms, a sms_management zostaw dla poświadczenia, które konfiguruje obszar roboczy.
Wysyłanie SMS wyjaśnia, jak wygląda początkowa lista dozwolonych krajów i jak dodawany jest kraj macierzysty.
Ogranicz dzienne wydatki na SMS dla każdego kraju
Każdy kraj docelowy może mieć dzienny limit wydatków w walucie Twojego portfela. Gdy dzienne wydatki na ten kraj osiągną limit, nowe wiadomości do niego są odrzucane z 422 SMSDestinationDailySpendExceeded do północy UTC. Limit równy zero blokuje kraj.
Kody weryfikacyjne wysyłane przez SMS wliczają się do limitu. Po osiągnięciu limitu Verify przestaje wysyłać kody przez SMS do tego kraju i próbuje następnego kanału włączonego dla niego. Gdy nie zostaje żaden kanał, weryfikacja kończy się błędem 422 NoAvailableChannel.
Ustaw limit w tych samych trzech miejscach co listę dozwolonych krajów. To polecenie włącza Holandię i ogranicza wydatki na nią do 25 EUR dziennie w obszarze roboczym, którego portfel jest w EUR:
bird sms destinations update --destination "NL=true;25EUR"Limit nie jest dokładny. Zmiana limitu zaczyna obowiązywać przy wysyłce po maksymalnie minucie. Wydatki są liczone w chwili naliczenia opłaty za wiadomość, więc wiadomości już przyjęte mogą przekroczyć dzienny limit o swój koszt. Uwzględnij ten margines przy ustalaniu limitu. bird sms destinations list pokazuje limit każdego kraju i dzisiejsze wykorzystanie.
Ustawienie limitu wymaga tego samego uprawnienia zapisu sms_management co lista dozwolonych krajów, więc poświadczenie mające tylko sms nie może podnieść własnego limitu. Pełne zasady opisuje Wysyłanie SMS.
Ogranicz łączne wydatki portfelem przedpłaconym
Wysyłki w modelu pay-as-you-go są opłacane z przedpłaconego portfela organizacji. To, co się dzieje, gdy saldo nie pokrywa wysyłki, zależy od kanału:
- SMS i WhatsApp są odrzucane przez API z kodem
402. Wiadomość już przyjęta, której opłata się nie powiedzie, kończy się stanemrejectedi nie jest rozliczana. - E-mail w płatnym planie Email jest rozliczany krótko po wysłaniu, więc saldo może chwilowo spaść poniżej zera. Gdy w portfelu nie zostaje saldo ani kredyt, nowe e-maile są odrzucane z kodem
402do czasu doładowania. - Opłata naliczana przy doręczeniu, której saldo nie pokrywa, jest pomijana, a wiadomość i tak trafia do odbiorcy.
Pusty portfel wstrzymuje dalsze wydatki, ale nie ogranicza ich dokładnie do salda. Doładuj go z zapasem na wysyłki rozliczane po przyjęciu. Jeśli automatyczne doładowanie jest włączone, portfel uzupełnia się z zapisanej karty, gdy saldo spadnie poniżej ustalonego progu, więc samo saldo przestaje ograniczać wydatki agenta. Źródłem tych zasad jest Rozliczenia i użycie.
Operacje rozliczeniowe wymagają uprawnienia rozliczeniowego organizacji, org:billing. Klucz API nie może go mieć, więc żaden klucz nie doładuje portfela, nie zmieni planu ani nie odczyta użycia. Token OAuth może je mieć, jeśli osoba zatwierdzająca logowanie sama je posiada i przyznaje uprawnienia organizacji, jak może to zrobić właściciel organizacji. Poświadczenie z samodzielnej rejestracji ma je od początku. Daj agentowi działającemu bez nadzoru klucz z ograniczonymi zakresami, a doładowywanie pozostanie w rękach osób odpowiedzialnych za budżet.
Metody płatności i portfel opisuje doładowania, automatyczne doładowanie i alerty o niskim saldzie.
Następne kroki
- Samodzielna rejestracja: utwórz z terminala konto, w którym działa agent.
- Uwierzytelnianie i klucze API: zakresy, wygasanie, rotacja i unieważnianie.
- Limity liczby żądań: limity żądań obowiązujące dla wszystkich kluczy Twojej organizacji.
- Przydziel agentowi własny numer telefonu i skrzynkę odbiorczą: tożsamości, za pomocą których agent wysyła i odbiera wiadomości.
Powiązane zasoby
Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.