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 |
| api_keys | Crear y revocar claves API | 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 |
| 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 |
| Enviar mensajes de WhatsApp | write | read | read | |
| whatsapp_management | Gestionar plantillas y ajustes de WhatsApp | write | write | read |
| assets | Subir, actualizar y eliminar recursos y carpetas | write | write | read |
| compliance | Gestionar identidades de registro, envíos y evidencia | write | write | read |
| 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 |
| 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 |
| 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 y la configuración. Un developer puede crear integraciones, gestionar dominios y webhooks, y crear claves de API. Un analyst tiene acceso de solo lectura.
Dos filas merecen atención. ip_pools es de solo lectura incluso para admins porque comprar IPs dedicadas y gestionar pools requiere el alcance org:ip_pools:write a nivel de organización. Los permisos de WhatsApp también separan la gestión del envío de mensajes. Un developer puede gestionar plantillas y configuración con whatsapp_management:write, pero solo leer mensajes con whatsapp:read; el envío queda restringido a admins. Otros productos añaden alcances usando el mismo modelo {scope, level}.
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. Dos 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.
- 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 puede invitar a otro owner o billing_admin. Esa invitación requiere org:members:write, que solo los owners tienen.
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-Id en endpoints con alcance de organización, X-Workspace-Id en 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 sobre este tema. Los recursos están en inglés.