Sign inGet Started

Agent-Kontrollen: eingeschränkte Schlüssel, Ausgabenlimits und sichere erneute Versuche

Ein Agent, der über Bird sendet, besitzt Zugangsdaten und gibt Ihr Guthaben aus. Fünf Kontrollen begrenzen, was er tun kann. Die erste sind die Zugangsdaten selbst. Die anderen vier greifen nur, solange die Zugangsdaten des Agenten sie nicht ändern können. Beginnen Sie deshalb mit den Zugangsdaten.

KontrolleWas sie begrenztWas der Aufrufer am Limit erhältWer sie festlegt
ZugangsdatenDie Operationen, die der Agent aufrufen kann403Die Person, die den Schlüssel erstellt oder die Anmeldung genehmigt
IdempotenzschlüsselDoppelte Sendungen, wenn eine Anfrage erneut versucht wirdDie ursprüngliche Antwort, erneut ausgeliefertDer Aufrufer, bei jeder Anfrage
SMS-Zielland-AllowlistDie Länder, in die eine SMS-API-Sendung gehen kann422 SMSDestinationNotEnabledEin Zugangsdaten-Satz mit sms_management-Schreibrecht
Tägliches SMS-AusgabenlimitSMS-Ausgaben für ein Land pro Tag422 SMSDestinationDailySpendExceededEin Zugangsdaten-Satz mit sms_management-Schreibrecht
Prepaid-WalletAusgaben im Pay-as-you-go-Modell402 für SMS und WhatsApp. Kostenpflichtige E-Mails werden nach dem Versand abgerechnet.Ein Organisationsinhaber oder Abrechnungsadministrator

Die Zielland-Allowlist und das tägliche Ausgabenlimit auf dieser Seite gelten für SMS. Verify und Voice haben jeweils eigene Zieleinstellungen mit anderen Ausgangswerten. Für E-Mail und WhatsApp gibt es weder eine Zielland-Allowlist noch ein tägliches Ausgabenlimit. Dort begrenzen nur die Scopes der Zugangsdaten und das Wallet, was ein Agent tun kann.

Wählen Sie die Zugangsdaten für den Agenten

Ein Agent ruft Bird mit einer von zwei Arten von Zugangsdaten auf. Sie unterscheiden sich darin, wie weit ihre Befugnisse reichen.

  • Ein API-Schlüssel (bk_) trägt die Scopes, die Sie ihm zuweisen, und gehört zu genau einem Workspace. Er kann keinen weiteren Schlüssel ausstellen und hat keinen Zugriff auf Abrechnung, Mitglieder oder Einstellungen der Organisation. Ihr Code sendet ihn als Bearer-Token. Die CLI und der lokale MCP-Server (bird mcp) verwenden den Schlüssel aus BIRD_API_KEY, sofern er gesetzt ist, und bevorzugen ihn gegenüber einer gespeicherten Anmeldung.
  • Ein OAuth-Token (bt_) erhalten die CLI und der MCP-Server, nachdem sich eine Person angemeldet hat. Es trägt die Berechtigungen, die diese Person genehmigt hat, und nie mehr, als sie selbst besitzt. Dazu können Schreibzugriff auf api_keys, Schreibzugriff auf sms_management und die Abrechnung der Organisation gehören. Ein Agent mit einem solchen Token kann Schlüssel ausstellen, Länder freischalten und die Limits auf dieser Seite erhöhen.

Was ein OAuth-Token darf, hängt davon ab, wie es erstellt wurde:

  • bird auth login fordert Lesezugriff an. --scope fordert die von Ihnen genannten Berechtigungen an, und --yolo fordert alle Berechtigungen an, die Sie delegieren können. Sie genehmigen das Ergebnis im Browser.
  • Ein gehosteter MCP-Client kann alle Berechtigungen anfordern, die Sie delegieren können. Auf dem Zustimmungsbildschirm wählen Sie aus, welche Sie erteilen. Entfernen Sie vor der Genehmigung die Häkchen bei allen Berechtigungen, die der Agent nicht benötigt.
  • Self-serve signup hat keinen Zustimmungsbildschirm. Die dabei erstellten Zugangsdaten besitzen jede Berechtigung, die der Inhaber der neuen Organisation delegieren kann, einschließlich der Abrechnung der Organisation.

Für einen Agenten, der unbeaufsichtigt läuft, erstellen Sie einen eingeschränkten API-Schlüssel und geben dem Agenten diesen Schlüssel. Die umfassendere Anmeldung behalten Sie der Person vor, die den Workspace konfiguriert. Die Anmeldung eines Tools widerrufen Sie unter Profile > Connected apps. API-Schlüssel und OAuth-Tokens vergleicht die beiden Arten von Zugangsdaten.

Jeden Schlüssel auf die benötigten Produkte beschränken

Ein API-Schlüssel enthält eine Liste von Scopes, jeweils ein Produktbereich auf read- oder write-Ebene. Ein Schlüssel, der nur SMS sendet, besitzt sms:write. Eine Anfrage außerhalb der Scopes des Schlüssels gibt 403 zurück. Ein geleakter oder missbrauchter Schlüssel erreicht daher nur, was Sie ihm gewährt haben.

Drei Eigenschaften gelten für jeden Schlüssel, unabhängig von seinen Scopes:

  • Ein Schlüssel kann keinen weiteren Schlüssel ausstellen. Für das Ausstellen und Rotieren von Schlüsseln ist api_keys:write nötig, das für API-Schlüssel nicht verfügbar ist. Eine Person genehmigt dies in einer Dashboard-Sitzung oder über eine Anmeldung per CLI oder MCP.
  • Ein Schlüssel endet an seinem Workspace. Er erreicht weder die Abrechnung noch die Mitglieder oder Einstellungen der Organisation.
  • Ein Schlüssel kann ablaufen. Setzen Sie beim Erstellen expires_at, dann gibt der Schlüssel nach diesem Zeitpunkt 401 zurück. Sie können einen Schlüssel jederzeit rotieren oder widerrufen.

Erstellen Sie einen Schlüssel im Dashboard oder im Terminal. Eine CLI-Anmeldung kann einem Schlüssel nur die Scopes geben, die sie selbst besitzt. Diese Anmeldung fordert deshalb zusätzlich zu api_keys:write auch sms:write an:

Codebeispiel
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Authentifizierung & API-Schlüssel enthält die Scope-Tabelle und behandelt Ablauf, Rotation und Widerruf.

Einen Versand erneut versuchen, ohne doppelt zu senden

Ein Agent, dem eine Antwort verloren geht, kann nicht erkennen, ob seine Anfrage angenommen wurde. Senden Sie für jeden beabsichtigten Versand einen Idempotency-Key-Header mit einem eindeutigen Wert. Ist das Ergebnis unbekannt, wiederholen Sie dieselbe Anfrage mit demselben Schlüssel. Bird gibt die ursprüngliche Antwort zurück und nimmt die Nachricht nur einmal an. Eine wiederholt ausgelieferte Antwort enthält Idempotency-Replay: true.

Garantiert ist ein akzeptierter Vorgang pro Schlüssel innerhalb des Aufbewahrungszeitraums. Die Garantie gilt für die Annahme durch API. Die Zustellung an das Telefon wird separat gemeldet, über den Nachrichtenstatus und seine Ereignisse.

Die SDKs erzeugen für jeden ändernden Aufruf einen Schlüssel und verwenden ihn für ihre automatischen erneuten Versuche wieder. Übergeben Sie in CLI den Wert --idempotency-key. Idempotenz beschreibt das Schlüsselformat, den Aufbewahrungszeitraum und was passiert, wenn ein Schlüssel mit einer anderen Anfrage wiederverwendet wird.

Jedes SMS-Zielland freigeben

Die Allowlist für SMS-Zielländer sperrt standardmäßig alles. Ein Versand über SMS API geht an ein auf der Liste freigegebenes Land, oder er wird mit 422 SMSDestinationNotEnabled abgelehnt, bevor ein Absender ermittelt wird. Es wird also keine Nachricht angenommen. Ein Agent, der auf ein unerwartetes Land zielt, wird abgewiesen. Das gilt für Sendungen aus Ihrem eigenen Code, aus bird sms send und aus dem Tool sms_send MCP.

Verifizierungscodes nutzen diese Liste nicht. Verify hat eine eigene Liste unter Verify destinations, in der jedes Land anfangs freigegeben ist. Ein Credential mit Schreibzugriff auf verify kann deshalb einen Code per SMS in ein Land senden, das diese Allowlist sperrt. Wenn der Agent verify hat, deaktivieren Sie auch auf dieser Seite die Länder, die Sie nicht bedienen.

Geben Sie ein Land unter SMS > Destinations, mit bird sms destinations update oder mit dem Tool sms_destinations_update MCP frei:

Codebeispiel
bird sms destinations update --destination NL=true

Zum Ändern der Allowlist ist der Scope sms_management auf write-Ebene nötig. Ein Credential, das nur sms hat, kann an die freigegebenen Länder senden, aber keine weiteren freigeben. Geben Sie dem sendenden Agenten sms und behalten Sie sms_management dem Credential vor, das den Workspace konfiguriert.

SMS senden erklärt, womit die Allowlist beginnt und wie das Heimatland hinzugefügt wird.

Tägliche SMS-Ausgaben pro Land begrenzen

Für jedes Zielland können Sie ein tägliches Ausgabenlimit in der Währung Ihres Wallets festlegen. Sobald die Tagesausgaben für dieses Land das Limit erreichen, werden neue Nachrichten dorthin bis Mitternacht UTC mit 422 SMSDestinationDailySpendExceeded abgelehnt. Ein Limit von null sperrt das Land.

Per SMS gesendete Verifizierungscodes zählen zum Limit. Ist das Limit erreicht, sendet Verify keine Codes mehr per SMS in dieses Land und versucht den nächsten dafür aktivierten Kanal. Bleibt kein Kanal übrig, schlägt die Verifizierung mit 422 NoAvailableChannel fehl.

Sie legen ein Limit an denselben drei Stellen fest wie die Allowlist. Dieser Befehl gibt die Niederlande frei und begrenzt sie auf 25 EUR pro Tag, in einem Workspace mit Wallet in EUR:

Codebeispiel
bird sms destinations update --destination "NL=true;25EUR"

Das Limit ist nicht exakt. Eine Änderung an einem Limit braucht bis zu einer Minute, bis sie beim Versand wirkt. Ausgaben werden gezählt, wenn eine Nachricht abgerechnet wird. Bereits angenommene Nachrichten können die Tagessumme daher um ihre Kosten über das Limit bringen. Planen Sie das Limit mit diesem Puffer. bird sms destinations list zeigt das Limit jedes Landes und die bisherige Tagesnutzung.

Zum Festlegen eines Limits brauchen Sie denselben sms_management-Schreibzugriff wie für die Allowlist. Ein Credential, das nur sms hat, kann sein eigenes Limit also nicht erhöhen. SMS senden enthält alle Regeln.

Gesamtausgaben mit dem Prepaid-Wallet begrenzen

Pay-as-you-go-Sendungen werden vom Prepaid-Wallet Ihrer Organisation abgebucht. Was passiert, wenn das Guthaben eine Sendung nicht deckt, hängt vom Kanal ab:

  • SMS und WhatsApp werden an der API mit 402 abgelehnt. Eine bereits angenommene Nachricht, deren Abbuchung fehlschlägt, endet mit rejected und wird nicht berechnet.
  • E-Mail in einem kostenpflichtigen Email-Tarif wird kurz nach dem Versand abgerechnet, sodass das Guthaben kurzzeitig unter null fallen kann. Sobald das Wallet kein Guthaben und keinen Kredit mehr hat, werden neue E-Mails mit 402 abgelehnt, bis Sie Guthaben aufladen.
  • Eine Gebühr zum Zustellzeitpunkt, die das Guthaben nicht deckt, entfällt, und die Nachricht erreicht ihren Empfänger trotzdem.

Ein leeres Wallet stoppt weitere Ausgaben, begrenzt sie aber nicht exakt auf das Guthaben. Laden Sie es mit einem Puffer für Sendungen auf, die erst nach der Annahme abgerechnet werden. Ist die automatische Aufladung aktiv, lädt sich das Wallet von einer gespeicherten Karte auf, sobald das Guthaben unter Ihren Schwellenwert fällt. Dann begrenzt das Guthaben allein nicht mehr, was ein Agent ausgeben kann. Billing & usage ist die Quelle für diese Regeln.

Abrechnungsvorgänge erfordern die Abrechnungsberechtigung der Organisation, org:billing. Ein API-Key kann sie nicht haben. Kein Key kann daher das Wallet aufladen, einen Tarif ändern oder die Nutzung lesen. Ein OAuth-Token kann sie haben, wenn die Person, die die Anmeldung bestätigt, sie selbst hat und Organisationsberechtigungen gewährt, wie es ein Organisationsinhaber kann. Das Credential aus der Self-Service-Registrierung hat sie von Anfang an. Geben Sie einem unbeaufsichtigten Agenten einen Key mit begrenzten Scopes, dann bleibt das Aufladen bei den Personen, die das Budget verantworten.

Zahlungsmethoden und Wallet behandelt Aufladungen, automatische Aufladung und Warnungen bei niedrigem Guthaben.

Nächste Schritte