Agentbeheer: beperkte sleutels, uitgavenlimieten en veilig opnieuw proberen
Een agent die via Bird verzendt, heeft een credential en geeft je saldo uit. Vijf maatregelen begrenzen wat hij kan doen. De eerste is de credential zelf. De andere vier werken alleen zolang de credential van de agent ze niet kan wijzigen, dus begin bij de credential.
| Maatregel | Wat het begrenst | Wat de aanroeper krijgt bij de limiet | Wie het instelt |
|---|---|---|---|
| Credential | De bewerkingen die de agent kan aanroepen | 403 | De persoon die de sleutel aanmaakt of de aanmelding goedkeurt |
| Idempotentiesleutel | Dubbele verzendingen wanneer een verzoek opnieuw wordt geprobeerd | Het oorspronkelijke antwoord, opnieuw afgespeeld | De aanroeper, bij elk verzoek |
| Toegestane bestemmingen voor SMS | De landen waarnaar een SMS API-verzending kan gaan | 422 SMSDestinationNotEnabled | Een credential met schrijfrechten voor sms_management |
| Daglimiet voor uitgaven aan SMS | Uitgaven aan SMS naar één land per dag | 422 SMSDestinationDailySpendExceeded | Een credential met schrijfrechten voor sms_management |
| Prepaid wallet | Uitgaven op basis van pay-as-you-go | 402 voor SMS en WhatsApp. Betaalde e-mail wordt na verzending in rekening gebracht. | Een eigenaar of factuurbeheerder van de organisatie |
De toegestane bestemmingen en de dagelijkse uitgavenlimiet op deze pagina gelden voor SMS. Verify en Voice hebben elk hun eigen bestemmingsinstellingen, met een andere beginstand. E-mail en WhatsApp hebben geen lijst met toegestane bestemmingen en geen dagelijkse uitgavenlimiet, dus daar begrenzen de scopes van de credential en de wallet wat een agent kan doen.
Kies de credential die de agent krijgt
Een agent roept Bird aan met een van twee soorten credentials. Ze verschillen in hoe ver hun bereik gaat.
- Een API-sleutel (
bk_) heeft de scopes die je eraan geeft en hoort bij één werkruimte. De sleutel kan geen andere sleutel uitgeven en heeft geen toegang tot facturering, leden of instellingen van de organisatie. Je code stuurt de sleutel mee als bearer-token. De CLI en de lokale MCP-server (bird mcp) gebruiken de sleutel inBIRD_API_KEYals die is ingesteld, in plaats van een opgeslagen aanmelding. - Een OAuth-token (
bt_) is wat de CLI en de MCP-server bewaren nadat iemand zich heeft aangemeld. Het token heeft de rechten die die persoon heeft goedgekeurd, en nooit meer dan die persoon zelf heeft. Daartoe kunnen schrijfrechten voorapi_keys, schrijfrechten voorsms_managementen facturering van de organisatie behoren. Een agent met zo'n token kan sleutels uitgeven, landen inschakelen en de limieten op deze pagina verhogen.
Wat een OAuth-token kan, hangt af van hoe het is aangemaakt:
bird auth loginvraagt om alleen-lezentoegang.--scopevraagt om de rechten die je opgeeft, en--yolovraagt om alle rechten die je kunt delegeren. Je keurt het resultaat goed in de browser.- Een gehoste MCP-client kan om alle rechten vragen die je kunt delegeren. Op het toestemmingsscherm kies je welke je verleent. Vink de rechten uit die de agent niet nodig heeft voordat je goedkeurt.
- Self-serve signup heeft geen toestemmingsscherm. De credential die het aanmaakt, heeft elke machtiging die de eigenaar van de nieuwe organisatie kan delegeren, inclusief facturering van de organisatie.
Maak voor een agent die zonder toezicht draait een API-sleutel met beperkte scopes aan en geef de agent die sleutel. Bewaar de ruimere aanmelding voor de persoon die de werkruimte configureert. Je kunt de aanmelding van een tool intrekken onder Profile > Connected apps. API-sleutels en OAuth-tokens vergelijkt de twee soorten credentials.
Beperk elke sleutel tot de producten die hij nodig heeft
Een API-sleutel heeft een lijst met scopes, elk een productgebied op read- of write-niveau. Een sleutel die alleen SMS verstuurt, heeft sms:write. Een verzoek buiten de scopes van de sleutel geeft 403 terug, zodat een uitgelekte of misbruikte sleutel alleen bereikt wat je hem hebt toegekend.
Drie eigenschappen van een sleutel gelden ongeacht de scopes:
- Een sleutel kan geen andere sleutel uitgeven. Voor het uitgeven en roteren van sleutels is
api_keys:writenodig, en dat is niet beschikbaar voor API-sleutels. Een persoon keurt dit goed in een dashboardsessie of via een aanmelding met CLI of MCP. - Een sleutel blijft binnen zijn werkruimte. Hij kan niet bij facturering, leden van de organisatie of instellingen van de organisatie.
- Een sleutel kan verlopen. Stel
expires_atin wanneer je hem aanmaakt; na dat moment geeft de sleutel401terug. Je kunt een sleutel op elk moment roteren of intrekken.
Maak een sleutel aan in het dashboard of vanuit een terminal. Een CLI-aanmelding kan aan een sleutel alleen de scopes geven die de aanmelding zelf heeft. Daarom vraagt deze om sms:write naast api_keys:write:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeAuthenticatie en API-sleutels bevat de scopetabel en behandelt verloop, rotatie en intrekking.
Een verzending opnieuw proberen zonder dubbel te versturen
Een agent die een antwoord kwijtraakt, weet niet of het verzoek is geaccepteerd. Stuur voor elke beoogde verzending een Idempotency-Key-header met een unieke waarde mee. Herhaal hetzelfde verzoek met dezelfde sleutel als de uitkomst onbekend is. Bird geeft dan het oorspronkelijke antwoord terug en accepteert het bericht één keer. Een herhaald antwoord bevat Idempotency-Replay: true.
De garantie is één geaccepteerde bewerking per sleutel binnen de bewaartermijn. Die geldt voor acceptatie door de API. Aflevering op de telefoon wordt apart gerapporteerd, via de berichtstatus en de bijbehorende events.
De SDK's genereren een sleutel voor elke wijzigende aanroep en gebruiken die opnieuw wanneer ze automatisch opnieuw proberen. Geef op de CLI --idempotency-key mee. Idempotentie beschrijft het sleutelformaat, de bewaartermijn en wat er gebeurt als een sleutel opnieuw wordt gebruikt met een ander verzoek.
Sta elk SMS-bestemmingsland toe
De SMS-allowlist voor bestemmingen weigert standaard. Een verzending via de SMS API gaat naar een land dat op de lijst is ingeschakeld, of wordt geweigerd met 422 SMSDestinationNotEnabled voordat er een afzender wordt bepaald, zodat er geen bericht wordt geaccepteerd. Een agent die op een onverwacht land is gericht, wordt geweigerd. Dit geldt voor een verzending vanuit je eigen code, vanuit bird sms send en vanuit de sms_send-tool MCP.
Verificatiecodes gebruiken deze lijst niet. Verify heeft een eigen lijst onder Verify destinations, waar elk land standaard is ingeschakeld. Een credential met schrijfrechten voor verify kan daardoor een code via SMS sturen naar een land dat deze allowlist blokkeert. Heeft de agent verify, schakel dan ook op die pagina de landen uit die je niet bedient.
Schakel een land in onder SMS > Destinations, met bird sms destinations update of met de sms_destinations_update-tool MCP:
bird sms destinations update --destination NL=trueOm de allowlist te wijzigen heb je de scope sms_management op write-niveau nodig. Een credential met alleen sms kan naar de ingeschakelde landen versturen, maar kan geen landen toevoegen. Geef de verzendende agent sms en bewaar sms_management voor de credential die de werkruimte configureert.
SMS versturen legt uit hoe de allowlist begint en hoe het thuisland wordt toegevoegd.
Beperk de dagelijkse SMS-uitgaven per land
Elk bestemmingsland kan een dagelijkse uitgavenlimiet hebben, in de valuta van je wallet. Zodra de uitgaven van die dag aan dat land de limiet bereiken, worden nieuwe berichten naar dat land tot middernacht UTC geweigerd met 422 SMSDestinationDailySpendExceeded. Een limiet van nul blokkeert het land.
Verificatiecodes die via SMS worden verstuurd, tellen mee voor de limiet. Wanneer de limiet is bereikt, stopt Verify met het versturen van codes via SMS naar dat land en probeert het het volgende kanaal dat voor dat land is ingeschakeld. Als er geen kanaal meer over is, mislukt de verificatie met 422 NoAvailableChannel.
Stel een limiet in op dezelfde drie plekken als de allowlist. Deze opdracht schakelt Nederland in en beperkt het tot 25 EUR per dag, in een werkruimte waarvan de wallet in EUR is:
bird sms destinations update --destination "NL=true;25EUR"De limiet is niet exact. Een gewijzigde limiet heeft tot een minuut nodig voordat hij geldt bij het verzenden. Uitgaven tellen mee op het moment dat een bericht in rekening wordt gebracht. Berichten die al zijn geaccepteerd, kunnen het dagtotaal daardoor met hun kosten boven de limiet brengen. Houd bij het plannen van de limiet rekening met die marge. bird sms destinations list toont per land de limiet en het verbruik van die dag.
Voor het instellen van een limiet is dezelfde sms_management-schrijftoegang nodig als voor de allowlist. Een credential met alleen sms kan zijn eigen limiet dus niet verhogen. SMS verzenden bevat de volledige regels.
Begrens de totale uitgaven met de prepaid wallet
Pay-as-you-go-verzendingen worden betaald uit de prepaid wallet van je organisatie. Wat er gebeurt als het saldo een verzending niet dekt, hangt af van het kanaal:
- SMS en WhatsApp worden bij de API geweigerd met
402. Een bericht dat al was geaccepteerd toen de afschrijving mislukte, eindigt alsrejecteden wordt niet gefactureerd. - E-mail met een betaald Email-abonnement wordt kort na verzending in rekening gebracht, waardoor het saldo even onder nul kan komen. Zodra de wallet geen saldo of tegoed meer heeft, wordt nieuwe e-mail geweigerd met
402totdat er geld is bijgestort. - Een kostenpost bij aflevering die het saldo niet dekt, wordt overgeslagen en het bericht bereikt de ontvanger toch.
Een lege wallet stopt verdere uitgaven, maar beperkt de uitgaven niet exact tot het saldo. Stort een marge bij voor verzendingen die pas na acceptatie in rekening worden gebracht. Als automatisch opwaarderen aan staat, vult de wallet zich via een opgeslagen kaart aan zodra het saldo onder je drempel zakt. Het saldo alleen begrenst dan niet meer wat een agent kan uitgeven. Facturering en gebruik is de bron voor deze regels.
Factureringsbewerkingen vereisen de factureringsrechten van de organisatie, org:billing. Een API-sleutel kan die niet hebben, dus geen enkele sleutel kan de wallet opwaarderen, een abonnement wijzigen of gebruik inzien. Een OAuth-token kan ze wel hebben als de persoon die de aanmelding goedkeurt ze zelf heeft en organisatierechten toekent, zoals een eigenaar van de organisatie kan. De credential uit self-serve aanmelding heeft ze vanaf het begin. Geef een agent die zonder toezicht draait een sleutel met beperkte scopes, zodat het bijstorten bij de mensen blijft die het budget beheren.
Betaalmethoden en wallet behandelt opwaarderen, automatisch opwaarderen en meldingen bij een laag saldo.
Volgende stappen
- Self-serve aanmelding: maak vanuit een terminal het account aan waarin een agent werkt.
- Authenticatie en API-sleutels: scopes, verloop, rotatie en intrekking.
- Rate limits: de limieten op verzoeken die gelden voor alle sleutels van je organisatie.
- Geef een agent een eigen telefoonnummer en inbox: de identiteiten waarmee een agent berichten verstuurt en ontvangt.
Gerelateerde bronnen
Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.