Sign inGet Started

Controles para agentes: claves con alcance limitado, límites de gasto y reintentos seguros

Un agente que envía a través de Bird tiene una credencial y gasta tu saldo. Cinco controles limitan lo que puede hacer. El primero es la propia credencial. Los otros cuatro solo funcionan mientras la credencial del agente no pueda modificarlos, así que empieza por la credencial.

ControlQué limitaQué recibe quien llama al alcanzar el límiteQuién lo configura
CredencialLas operaciones que puede llamar el agente403La persona que crea la clave o aprueba el inicio de sesión
Clave de idempotenciaEnvíos duplicados cuando se reintenta una solicitudLa respuesta original, reproducida de nuevoQuien llama, en cada solicitud
Lista de destinos permitidos de SMSLos países a los que puede ir un envío API de SMS422 SMSDestinationNotEnabledUna credencial con permiso de escritura en sms_management
Límite de gasto diario de SMSGasto de SMS en un país durante un día422 SMSDestinationDailySpendExceededUna credencial con permiso de escritura en sms_management
Monedero prepagoEl gasto de pago por uso402 para SMS y WhatsApp. El email de pago se cobra después de enviarse.Un propietario de la organización o un administrador de facturación

La lista de destinos permitidos y el límite de gasto diario de esta página se aplican a SMS. Verify y Voice tienen cada uno su propia configuración de destinos, y su estado inicial es distinto. El email y WhatsApp no tienen lista de destinos permitidos ni límite de gasto diario, así que allí lo que limita a un agente son los ámbitos de la credencial y el monedero.

Elige la credencial que usa el agente

Un agente llama a Bird con uno de dos tipos de credencial. Se diferencian en su alcance.

  • Una clave de API (bk_) lleva los ámbitos que le asignas y pertenece a un solo espacio de trabajo. No puede emitir otra clave ni acceder a la facturación, los miembros o la configuración de la organización. Tu código la envía como token bearer. La CLI y el servidor local de MCP (bird mcp) usan la clave de BIRD_API_KEY cuando está definida, con preferencia sobre un inicio de sesión guardado.
  • Un token de OAuth (bt_) es lo que guardan la CLI y el servidor de MCP después de que una persona inicia sesión. Lleva los permisos que esa persona aprobó, y nunca más de los que ella tiene. Entre ellos pueden estar la escritura en api_keys, la escritura en sms_management y la facturación de la organización. Un agente con un token así puede emitir claves, habilitar países y subir los límites de esta página.

Lo que puede hacer un token de OAuth depende de cómo se creó:

  • bird auth login solicita acceso de solo lectura. --scope solicita el conjunto que indiques, y --yolo solicita todos los permisos que puedes delegar. Apruebas el resultado en el navegador.
  • Un cliente de MCP alojado puede solicitar todos los permisos que puedes delegar. La pantalla de consentimiento te permite seleccionar cuáles conceder. Desmarca los que el agente no necesita antes de aprobar.
  • El registro autoservicio no tiene pantalla de consentimiento. La credencial que crea tiene todos los permisos que el propietario de la nueva organización puede delegar, incluida la facturación de la organización.

Para un agente que funciona sin supervisión, crea una clave API con alcances limitados y dásela al agente. Reserva el inicio de sesión más amplio para la persona que configura el espacio de trabajo. Puedes revocar el inicio de sesión de una herramienta en Profile > Connected apps. Claves API y tokens OAuth compara los dos tipos de credencial.

Limita cada clave a los productos que necesita

Una clave API lleva una lista de alcances, cada uno un área de producto con nivel read o write. Una clave que solo envía SMS tiene sms:write. Una solicitud fuera de los alcances de la clave devuelve 403, así que una clave filtrada o mal usada solo llega a lo que le concediste.

Tres propiedades de una clave se cumplen sean cuales sean sus alcances:

  • Una clave no puede emitir otra clave. Emitir y rotar claves requiere api_keys:write, que no está disponible para las claves API. Una persona lo aprueba en una sesión del dashboard o en un inicio de sesión de CLI o MCP.
  • Una clave no sale de su espacio de trabajo. No puede acceder a la facturación, a los miembros de la organización ni a la configuración de la organización.
  • Una clave puede caducar. Define expires_at al crearla y la clave devolverá 401 a partir de ese momento. Puedes rotar o revocar una clave en cualquier momento.

Crea una clave en el dashboard o desde un terminal. Un inicio de sesión de CLI solo puede asignar a una clave los alcances que él mismo tiene, por eso este pide sms:write además de api_keys:write:

Ejemplo de código
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Autenticación y claves API incluye la tabla de alcances y explica la caducidad, la rotación y la revocación.

Reintentar un envío sin enviar dos veces

Un agente que pierde una respuesta no puede saber si su solicitud se aceptó. Envía un encabezado Idempotency-Key con un valor único para cada envío previsto y, si no conoces el resultado, repite la misma solicitud con la misma clave. Bird devuelve la respuesta original y acepta el mensaje una sola vez. Una respuesta repetida lleva Idempotency-Replay: true.

La garantía es una sola operación aceptada por clave dentro del periodo de retención. Cubre la aceptación por parte de API. La entrega al teléfono se informa por separado, mediante el estado del mensaje y sus eventos.

Los SDK generan una clave para cada llamada que modifica datos y la reutilizan en sus reintentos automáticos. En CLI, pasa --idempotency-key. Idempotencia explica el formato de la clave, el periodo de retención y qué ocurre cuando se reutiliza una clave con una solicitud distinta.

Permite cada país de destino de SMS

La lista de destinos permitidos de SMS deniega todo por defecto. Un envío a través de SMS API llega a un país habilitado en la lista, o se rechaza con 422 SMSDestinationNotEnabled antes de resolver un remitente, de modo que no se acepta ningún mensaje. Si un agente apunta a un país inesperado, el envío se rechaza. Esto se aplica a los envíos desde tu propio código, desde bird sms send y desde la herramienta sms_send MCP.

Los códigos de verificación no usan esta lista. Verify tiene su propia lista en Destinos de Verify, donde todos los países empiezan habilitados. Por eso, una credencial con permiso de escritura en verify puede enviar un código por SMS a un país que esta lista bloquea. Si el agente tiene verify, desactiva también en esa página los países a los que no das servicio.

Habilita un país en SMS > Destinations, con bird sms destinations update o con la herramienta sms_destinations_update MCP:

Ejemplo de código
bird sms destinations update --destination NL=true

Para cambiar la lista de permitidos hace falta el ámbito sms_management a nivel write. Una credencial que solo tiene sms puede enviar a los países habilitados, pero no puede habilitar más. Da al agente que envía sms y reserva sms_management para la credencial que configura el espacio de trabajo.

Envío de SMS explica cómo empieza la lista de permitidos y cómo se añade el país de origen.

Limita el gasto diario de SMS por país

Cada país de destino puede tener un límite de gasto diario, en la moneda de tu monedero. Cuando el gasto del día en ese país alcanza el límite, los mensajes nuevos a ese país se rechazan con 422 SMSDestinationDailySpendExceeded hasta la medianoche UTC. Un límite de cero bloquea el país.

Los códigos de verificación enviados por SMS cuentan para el límite. Cuando se alcanza el límite, Verify deja de enviar códigos por SMS a ese país y prueba el siguiente canal habilitado para él. Si no queda ningún canal, la verificación falla con 422 NoAvailableChannel.

Configura un límite en los mismos tres lugares que la lista de permitidos. Este comando habilita los Países Bajos y los limita a 25 EUR al día, en un espacio de trabajo cuyo monedero está en EUR:

Ejemplo de código
bird sms destinations update --destination "NL=true;25EUR"

El límite no es exacto. Un cambio en un límite tarda hasta un minuto en aplicarse a los envíos. El gasto se contabiliza cuando se cobra un mensaje, así que los mensajes ya aceptados pueden llevar el total del día por encima del límite en lo que cuesten. Fija el límite con ese margen. bird sms destinations list muestra el límite de cada país y el consumo del día respecto a él.

Para fijar un límite se necesita el mismo acceso de escritura de sms_management que para la lista de permitidos, así que una credencial que solo tiene sms no puede subir su propio límite. Envío de SMS recoge las reglas completas.

Limita el gasto total con el monedero prepago

Los envíos de pago por uso se descuentan del monedero prepago de tu organización. Lo que ocurre cuando el saldo no cubre un envío depende del canal:

  • SMS y WhatsApp se rechazan en la API con 402. Un mensaje que ya se había aceptado cuando falla su cobro termina en rejected y no se factura.
  • El email con un plan de Email de pago se cobra poco después de enviarse, así que el saldo puede quedar brevemente por debajo de cero. Cuando el monedero se queda sin saldo ni crédito, el email nuevo se rechaza con 402 hasta que añadas fondos.
  • Una tarifa en el momento de la entrega que el saldo no cubre se omite, y el mensaje llega igualmente a su destinatario.

Un monedero vacío detiene el gasto posterior, pero no limita el gasto exactamente al saldo. Recárgalo con margen para los envíos que se cobran después de aceptarse. Si la recarga automática está activada, el monedero se recarga con una tarjeta guardada cuando el saldo baja de tu umbral, así que el saldo ya no limita por sí solo lo que puede gastar un agente. Facturación y uso es la fuente de estas reglas.

Las operaciones de facturación necesitan el permiso de facturación de la organización, org:billing. Una clave de API no puede tenerlo, así que ninguna clave puede recargar el monedero, cambiar de plan ni consultar el uso. Un token de OAuth puede tenerlo si la persona que aprueba el inicio de sesión lo tiene y concede permisos de organización, como puede hacer el propietario de una organización. La credencial del registro autoservicio lo tiene desde el principio. Da a un agente desatendido una clave con ámbitos limitados, y añadir fondos seguirá en manos de las personas responsables del presupuesto.

Métodos de pago y monedero explica las recargas, la recarga automática y las alertas de saldo bajo.

Siguientes pasos