Sign inGet Started

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:

AlcanceQué significa writeadmindeveloperanalyst
workspaceEditar ajustes del espacio de trabajo (nombre, notificaciones)writereadread
access_restrictionsGestionar las listas de IP permitidas del espacio de trabajowritenonenone
api_keysCrear y revocar claves de APIwritewritenone
service_accountsRevisar y revocar integraciones de plataformas conectadaswritewritenone
emailsEnviar correo electrónicowritewriteread
email_managementGestionar supresiones y configuración de correo electrónicowritewriteread
email_marketingGestionar contactos, audiencias y difusioneswritewriteread
inbox_insightsConfigurar Inbox Insights y ver datos de ubicación en bandejawritewriteread
competitiveGestionar listas de seguimiento de Competitive Insightswritenoneread
domainsAñadir, verificar y eliminar dominios de envíowritewriteread
webhooksConfigurar endpoints de webhookwritewriteread
smsEnviar SMSwritewriteread
sms_managementGestionar remitentes, supresiones y ajustes de SMSwritewriteread
verifyEnviar y comprobar códigos de verificaciónwritewriteread
verify_managementConfigurar remitentes y países de verificaciónwritewriteread
whatsappEnviar mensajes de WhatsAppwritewriteread
whatsapp_managementGestionar plantillas y ajustes de WhatsAppwritewriteread
ambEnviar mensajes de Apple Messages for Businesswritewriteread
amb_managementGestionar registros comerciales, reglas de enrutamiento y supresiones de Apple Messageswritewriteread
assetsSubir, actualizar y eliminar recursos y carpetaswritewriteread
automationsCrear, publicar y ejecutar automatizaciones del espacio de trabajowritewriteread
complianceGestionar identidades de registro, envíos y evidenciawritewriteread
esimCrear pedidos de eSIM y gestionar eSIMswritewriteread
esim_credentialsVer y gestionar las credenciales de instalación de eSIMwritewritenone
lookupBuscar números de teléfono, direcciones de correo y coincidencias de identidadwritewritenone
mailboxEnviar y responder mensajes de buzónwritewriteread
mailbox_managementCrear, actualizar y eliminar buzones y reglas de recepciónwritewriteread
numbersBuscar, comprar, configurar y liberar números de teléfonowritewriteread
preferencesRegistrar y eliminar preferencias de mensajería entre canaleswritewriteread
realtimeCrear apps y publicar eventoswritewriteread
voiceLeer registros de tramos y estadísticas, y realizar llamadaswritewriteread
voice_managementGestionar troncales, gateways, números, caller IDs y destinoswritewriteread
ip_poolsVer los pools de IP de la organización (solo lectura)readreadread
trustVer los requisitos de confianza de la organización (solo lectura)readreadread
membersGestionar el equipo y las invitaciones del espacio de trabajowritereadread
analyticsVer informes y analíticas de entregabilidadreadnoneread
auditVer el registro de auditoríareadnoneread
request_logsVer el registro de solicitudes (solo lectura)readreadread

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:write y org:audit:read), además de acceso admin automá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).

La configuración de Team del espacio de trabajo en el dashboard de Bird, con la lista de miembros, su rol y la acción de invitar miembros

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-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

Continúa con la documentación, guías y ejemplos de este tema.