Usuarios, equipos y roles
El acceso en Bird se basa en roles: un usuario tiene un rol en tu espacio de trabajo, y cada rol es un conjunto fijo de permisos. No necesitas configurar nada más; elige el rol adecuado y los permisos se aplican solos.
Los roles determinan lo que las personas pueden hacer en el dashboard. Lo que los servicios pueden hacer se controla con los alcances de las claves de API: el mismo vocabulario de permisos, otorgado por clave en lugar de por rol.
Roles de espacio de trabajo
Los roles con los que trabajas día a día están en el espacio de trabajo (consulta Workspace): admin, developer y analyst. Gestiónalos en el dashboard en Settings > Team.
Cada permiso es un par {scope, level}, donde level es read o write (write incluye read). Un rol es un conjunto fijo y nombrado de estos pares:
| Alcance | Qué significa write | admin | developer | analyst |
|---|---|---|---|---|
workspace | Editar ajustes del espacio de trabajo (nombre, notificaciones) | write | read | read |
access_restrictions | Gestionar las listas de IP permitidas del espacio de trabajo | write | none | none |
api_keys | Crear y revocar claves de API | write | write | none |
service_accounts | Revisar y revocar integraciones de plataformas conectadas | write | write | none |
emails | Enviar correo electrónico | write | write | read |
email_management | Gestionar supresiones y configuración de correo electrónico | write | write | read |
email_marketing | Gestionar contactos, audiencias y difusiones | write | write | read |
inbox_insights | Configurar Inbox Insights y ver datos de ubicación en bandeja | write | write | read |
competitive | Gestionar listas de seguimiento de Competitive Insights | write | none | read |
domains | Añadir, verificar y eliminar dominios de envío | write | write | read |
webhooks | Configurar endpoints de webhook | write | write | read |
sms | Enviar SMS | write | write | read |
sms_management | Gestionar remitentes, supresiones y ajustes de SMS | write | write | read |
verify | Enviar y comprobar códigos de verificación | write | write | read |
verify_management | Configurar remitentes y países de verificación | write | write | read |
whatsapp | Enviar mensajes de WhatsApp | write | write | read |
whatsapp_management | Gestionar plantillas y ajustes de WhatsApp | write | write | read |
amb | Enviar mensajes de Apple Messages for Business | write | write | read |
amb_management | Gestionar registros comerciales, reglas de enrutamiento y supresiones de Apple Messages | write | write | read |
assets | Subir, actualizar y eliminar recursos y carpetas | write | write | read |
automations | Crear, publicar y ejecutar automatizaciones del espacio de trabajo | write | write | read |
compliance | Gestionar identidades de registro, envíos y evidencia | write | write | read |
esim | Crear pedidos de eSIM y gestionar eSIMs | write | write | read |
esim_credentials | Ver y gestionar las credenciales de instalación de eSIM | write | write | none |
lookup | Buscar números de teléfono, direcciones de correo y coincidencias de identidad | write | write | none |
mailbox | Enviar y responder mensajes de buzón | write | write | read |
mailbox_management | Crear, actualizar y eliminar buzones y reglas de recepción | write | write | read |
numbers | Buscar, comprar, configurar y liberar números de teléfono | write | write | read |
preferences | Registrar y eliminar preferencias de mensajería entre canales | write | write | read |
realtime | Crear apps y publicar eventos | write | write | read |
voice | Leer registros de tramos y estadísticas, y realizar llamadas | write | write | read |
voice_management | Gestionar troncales, gateways, números, caller IDs y destinos | write | write | read |
ip_pools | Ver los pools de IP de la organización (solo lectura) | read | read | read |
trust | Ver los requisitos de confianza de la organización (solo lectura) | read | read | read |
members | Gestionar el equipo y las invitaciones del espacio de trabajo | write | read | read |
analytics | Ver informes y analíticas de entregabilidad | read | none | read |
audit | Ver el registro de auditoría | read | none | read |
request_logs | Ver el registro de solicitudes (solo lectura) | read | read | read |
En la práctica, un admin administra el espacio de trabajo, incluidos el equipo, las listas de IP permitidas y la configuración. Un developer puede crear integraciones en todos los canales, gestionar dominios y webhooks, y crear claves de API. Un analyst tiene acceso de solo lectura (y ningún acceso a alcances de solo escritura que gastan saldo del monedero, como lookup, ni a alcances que contienen secretos, como esim_credentials).
Dos filas de solo lectura merecen atención: ip_pools y trust son de solo lectura a nivel de espacio de trabajo incluso para admins, porque comprar IPs dedicadas (org:ip_pools:write) e iniciar verificaciones de confianza de la organización (org:trust:write) son operaciones a nivel de organización. Los alcances de canal separan el tráfico (emails, sms, whatsapp, amb, voice) de la configuración del canal (email_management, sms_management, whatsapp_management, amb_management, voice_management). Así puedes limitar con precisión las claves de API, aunque los roles de espacio de trabajo otorgan ambos al mismo nivel.
Un 403 en cualquier endpoint significa que el principal autenticado no tiene el {scope, level} que ese endpoint requiere. La solución es un cambio de rol (para una persona) o una nueva clave con los alcances adecuados (para un servicio).
Roles de organización
Detrás de tu espacio de trabajo hay una organización que gestiona la facturación y la lista general de miembros. Tres roles administran esa capa:
owner: todo. Lectura y escritura completas en operaciones de organización y espacio de trabajo. Una organización puede (y debería) tener varios owners. La persona que creó la cuenta comienza como owner.org_admin: administración de la organización (org:workspaces:write,org:master_keys:write,org:members:write,org:settings:write,org:access_restrictions:write,org:ip_pools:writeyorg:audit:read), además de accesoadminautomático en todos los espacios de trabajo de la organización.billing_admin: facturación y configuración de la organización (org:billing:write,org:settings:write) más acceso de lectura a la lista de miembros de la organización y metadatos del espacio de trabajo. Sin acceso a recursos dentro del espacio de trabajo.
Estos roles rara vez se usan en el día a día: la mayoría de los compañeros solo necesitan un rol de espacio de trabajo.
Miembros y el equipo
La membresía es implícita: un usuario es "in" tu organización si tiene un rol de organización o un rol de espacio de trabajo. No existe un registro de membresía separado que gestionar.
Gestionas las personas de tu espacio de trabajo en el dashboard en Settings > Team, protegido por el alcance members del espacio de trabajo; un admin del espacio de trabajo gestiona el equipo aquí sin necesidad de un rol a nivel de organización. La gestión del equipo es algo que hacen las personas, por lo que las claves de API no pueden tener el alcance members (consulta Authentication).

Eliminar el acceso de alguien al espacio de trabajo elimina ese rol sin modificar ningún rol de organización que tenga. Eliminar a alguien de la organización revoca todo su acceso a la cuenta. Las claves API que haya creado siguen funcionando porque cada clave pertenece al espacio de trabajo de forma independiente de su creador.
Invitaciones
Desde Settings > Team, invita una dirección de correo con un rol y Bird se encarga del resto. Detrás del botón hay una invitación inteligente: un solo flujo gestiona tanto a colegas que ya están en tu organización como a personas que nunca han oído hablar de Bird.
- Ya es miembro de la organización: se añade al espacio de trabajo de inmediato con el rol indicado. Sin correo, sin espera; la respuesta es un objeto member.
- Todavía no es miembro: Bird crea una invitación, le envía un enlace de registro por correo, y la respuesta es un objeto invitation con estado
pending. El enlace es válido durante 7 días; después la invitación expira y tienes que invitarle de nuevo.
El campo type de la respuesta (team_member o invitation) te indica qué ocurrió. Una segunda invitación pendiente para el mismo correo devuelve 409 en lugar de crear un duplicado, y puedes retirar una invitación pendiente en cualquier momento desde la misma página.
Un owner o un org_admin puede invitar con roles a nivel de organización (org:members:write). Solo un owner puede otorgar el rol owner.
Protecciones
Se aplican dos invariantes en cada cambio de rol, sin importar quién lo solicite:
- El último owner es inamovible. Degradar o eliminar al único owner de una organización devuelve
409: una organización nunca puede quedarse sin owner. Primero promueve a un segundo owner. - No puedes cambiar tu propio acceso. Cambiar tu propio rol o eliminarte a ti mismo devuelve
403. Esto evita tanto el bloqueo accidental como la autopromoción silenciosa; otro admin u owner tiene que hacer el cambio.
Cómo se selecciona el contexto
Los endpoints de miembros y equipo existen en dos niveles, y a qué organización o espacio de trabajo apunta una solicitud depende de cómo se autentique:
- Autenticación por sesión (el dashboard, o herramientas que actúan en tu nombre) proporciona contexto por solicitud:
X-Organization-Iden endpoints con alcance de organización,X-Workspace-Iden los de alcance de espacio de trabajo. - Las claves de API llevan su contexto de forma implícita. Una clave pertenece a tu espacio de trabajo, lo que también fija la organización; no se necesitan headers, y un header de contexto que contradiga la clave se rechaza como malformado (
400).
Consulta Workspace para el modelo completo de resolución de contexto.
Próximos pasos
- Authentication y claves de API: alcances para servicios, y quién puede gestionar claves
- Workspace: el espacio de trabajo al que se vinculan estos roles
- Billing & usage: qué gestionan los roles de facturación a nivel de organización
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.