Referencia de Control de Acceso

Capgo utiliza el control de acceso basado en rol (RBAC) para gestionar qué puede hacer cada miembro del equipo. Los roles se organizan por ámbito – desde toda la organización hasta un solo paquete.

Para una guía visual de la gestión de miembros en la consola, consulte Organización.

---

Ámbitos de rol

Cada rol pertenece a un ámbito que determina qué recurso concede acceso.

Ámbito	Aplica a	Ejemplo de uso
Organización	La organización completa y todos sus aplicativos	Tu cofundador obtiene Super Administrador; tu contable obtiene Administrador de facturación
Aplicación	Una aplicación individual y sus canales	Un contratista trabajando en una aplicación obtiene Desarrollador de Aplicación
Canales	Un canal único dentro de una aplicación	Un ingeniero de pruebas solo gestiona el staging canal
Paquete	Una versión de paquete única	Un revisor necesita acceso de lectura a una versión de lanzamiento específica

Un miembro puede tener un rol por ámbito objetivo — por ejemplo, un rol de organización, un rol en Aplicación A y un rol diferente en Aplicación B.

---

Roles de organización

Estos roles se asignan cuando se invita a un miembro. Otorgan acceso a toda la organización.

Rol	Nombre interno	Descripción
Administrador principal	org_super_admin	Equivalente a propietario. Control total, incluyendo la eliminación de la org, la gestión de facturación y la transferencia de aplicaciones. Se concede automáticamente al creador de la org.
Administrador	org_admin	Administración completa — gestionar miembros, aplicaciones, canales. No se puede eliminar la org, actualizar la facturación, transferir aplicaciones o promover a usuarios a Administrador principal.
Gerente de facturación	org_billing_admin	Acceso solo a facturación: ver y actualizar la información de facturación, facturas e historial de auditoría de facturación. Sin acceso a aplicaciones o miembros.
Miembro	org_member	Acceso lector para la org y todos sus apps.

Matriz de permisos de la organización

Permiso	Descripción	Administrador supremo	Administrador	Gerente de facturación	Miembro
org.read	Ver la organización	✅	✅	✅	✅
org.update_settings	Editar nombre de la org, logo, correo de administración	✅	✅	❌	❌
org.delete	Eliminar permanentemente la organización	✅	❌	❌	❌
org.read_members	Ver la lista de miembros	✅	✅	❌	✅
org.invite_user	Invitar nuevos miembros	✅	✅	❌	❌
org.update_user_roles	Cambiar roles de miembros (el administrador no puede promover a Super Administrador — bloqueado por la jerarquía de roles)	✅	✅	❌	❌
org.read_billing	Ver información de facturación y plan actual	✅	✅	✅	❌
org.update_billing	Actualizar método de pago y plan	✅	❌	✅	❌
org.read_invoices	Ver facturas	✅	✅	✅	❌
org.read_audit	Ver registro de actividad de la organización	✅	✅	❌	❌
org.read_billing_audit	Ver registro de auditoría específico de facturación	✅	✅	✅	❌

Nota

Los roles de la organización heredan todos los permisos de la aplicación, canal y paquete de roles debajo de ellos en la jerarquía. A Super Administrador puede hacer todo lo que un Administrador de Aplicación o Administrador de Canal puede hacer, en todos los aplicativos y canales.

---

Roles de Aplicación

Limitado a un solo aplicativo. Utilice estos cuando un miembro del equipo debe trabajar solo en un aplicativo, no en toda la organización.

Rol	Nombre interno	Descripción
Administrador de Aplicación	app_admin	Control total de una app — canales, dispositivos, roles de usuario para la app. No se puede eliminar o transferir la app (esas son operaciones de nivel de organización).
Desarrollador de Aplicación	app_developer	Cargar paquetes, gestionar dispositivos, desencadenar compilaciones nativas, actualizar configuraciones de canal. Sin eliminación, sin cambios en configuraciones de la app, sin creación de canales.
Subidor de Aplicación	app_uploader	Acceso de lectura + cargar nuevas versiones de paquetes.
Leer solo — estadísticas, paquetes, canales, registros, dispositivos.	app_reader	Vista previa de la aplicación
Ciclo de vida de la vista previa de la organización y la aplicación: cargar un paquete y crear un canal de vista previa. La creación de ese canal concede automáticamente derechos de ciclo de vida solo para él.	app_preview	Matriz de permisos de la aplicación

Título de la sección “Matriz de permisos de la aplicación”

App permission matrix	Descripción	Administrador de Aplicación	Desarrollador de Aplicación	Cargador de Aplicación	Leer Aplicación
app.read	Ver detalles de la aplicación, estadísticas y metadatos	✅	✅	✅	✅
app.update_settings	Editar ajustes de la aplicación	✅	❌	❌	❌
app.read_bundles	Ver la lista de paquetes subidos	✅	✅	✅	✅
app.upload_bundle	Subir una nueva versión de paquete	✅	✅	✅	❌
app.create_channel	Crear un nuevo canal	✅	❌	❌	❌
app.read_channels	Ver canales	✅	✅	✅	✅
app.read_logs	Ver registros de entrega de actualizaciones	✅	✅	✅	✅
app.manage_devices	Asignar, sobreescribir o desvincular dispositivos	✅	✅	❌	❌
app.read_devices	Ver la lista de dispositivos	✅	✅	✅	✅
app.build_native	Desencadenar una construcción nube nativa	✅	✅	❌	❌
app.read_audit	Ver el registro de actividad de nivel de aplicación	✅	✅	✅	✅
app.update_user_roles	Administrar asignaciones de roles de nivel de aplicación	✅	❌	❌	❌
bundle.delete	Eliminar un paquete	✅	❌	❌	❌

Nota

app.delete y app.transfer son operaciones de nivel de organización — solo org_super_admin pueden realizarlos, sin importar los roles de nivel de aplicación.

conjunto de permisos de vista previa de la aplicación

Usar Vista previa de la aplicación (app_preview) para una clave de CI vinculada a una organización y una aplicación que gestiona el ciclo de vida de una vista previa de PR sin acceso amplio a la aplicación o la organización.

El app_preview vinculación concede solo estos permisos de nivel de aplicación:

Permiso	Permite
app.read	Leer la aplicación seleccionada
app.read_bundles	Leer los paquetes subidos
app.upload_bundle	Subir un paquete
app.create_channel	Crear un canal

Cuando una clave de vista previa de la aplicación crea un canal, Capgo da automáticamente a esa clave una clave de enlace hijo para el nuevo canal: channel_preview Permiso

Permite	Leer el canal creado por la clave
channel.read	Establecer la propia clave de paquete subido en ese canal
channel.promote_bundle	Eliminar ese canal
channel.delete	Porque

retiene app_preview la clave puede enumerar metadatos de canales en la aplicación seleccionada. La unión de enlace hijo automática es un app.readporque retiene gestión límite: no concede mutaciones de ciclo de vida para un canal que la clave no creó.

Capgo registra la clave de vista previa que creó cada canal y subió cada paquete. Por lo tanto, una clave de vista previa de la aplicación puede crear cada canal de vista previa no público que necesita, promover su propio paquete y eliminar de manera atómica ese canal y paquete con channel delete --delete-bundle; no puede hacer esas cosas con un canal de predeterminado/main existente, un canal de otra clave de vista previa o un paquete de otra clave.

No incluye app.update_settings, la gestión de dispositivos o roles channel.update_settings, channel.rollback_bundle, la gestión de dispositivos forzada o genericos bundle.delete.

Advertencia

Cada vinculación de vista previa de la aplicación permanece vinculada a la organización propietaria del aplicativo seleccionado. El rol omite un rol organizativo; no elimina la asociación de organización. Revocar o expirar la vinculación de la aplicación elimina el acceso de ciclo de vida efectivo de la clave.

---

Roles de canal

Limitado a un canal único. Útil para dar acceso objetivo a un canal de liberación específico.

Nota

Los roles de canal están actualmente disponibles a través de API y CLI solo — no hay interfaz de usuario para asignarlos en la consola. channel_preview es una excepción: Capgo lo crea automáticamente para una clave de vista previa de aplicación cuando esa clave crea un canal. En la consola, utilice sobrescripciones de permisos de canal en su lugar para afinar el acceso de canal por usuario.

Rol	Nombre interno	Descripción
Administrador de canal	channel_admin	Control total de un canal: configuración, promoción/retorno de paquetes, gestión de dispositivos forzados.
Vista de canal	channel_reader	Leer solo — paquete actual, historia, dispositivos forzados, registro de auditoría.
Vista previa de canal	channel_preview	Asignado por el sistema al clave de vista previa de la aplicación que creó el canal: lectura, promoción de su propio paquete y eliminación de ese canal.

Matriz de permisos de canal

Permiso	Descripción	Administrador de canal	Vista de canal	Vista previa del canal
channel.read	Ver el canal y su paquete actual	✅	✅	✅
channel.update_settings	Editar ajustes del canal (también incluye opciones de plataforma, política de actualización…)	✅	❌	❌
channel.delete	Borrar el canal	✅	❌	✅
channel.read_history	Ver historial de asignación de paquetes	✅	✅	❌
channel.promote_bundle	Establecer el paquete activo en el canal	✅	❌	✅
channel.rollback_bundle	Revertir a un paquete anterior	✅	❌	❌
channel.manage_forced_devices	Forzar dispositivos específicos a este canal	✅	❌	❌
channel.read_forced_devices	Ver lista de dispositivos forzados	✅	✅	❌
channel.read_audit	Ver registro de actividad del canal	✅	✅	❌

---

Roles de paquete

Escalado a una sola versión de paquete. Rara vez necesario — la mayoría de los equipos utilizan roles de nivel de aplicación en su lugar.

Nota

Los roles de paquete están actualmente disponibles a través de API y CLI solo — no hay interfaz de usuario para asignarlos en la consola.

Rol	Nombre interno	Descripción
Administrador de paquete	bundle_admin	Leer, actualizar metadatos y eliminar un paquete específico.
Vista de paquete	bundle_reader	Acceso lector para un paquete específico.

---

Permisos de canal con prioridad (Panel de control)

En el panel de control, el acceso a los canales se determina por defecto según el rol de la aplicación del usuario. Para un control más detallado, puede superar permisos de canal específicos por usuario o grupo sin cambiar su rol de aplicación.

Los superamientos se configuran desde la pestaña Acceso del panel de control haciendo clic en el botón de permisos de canal (icono de escudo) junto a un usuario. Consulte Organización — Superando permisos de canal para una guía visual.

Permisos superables

Permiso	Descripción	Comportamiento por defecto
Lectura	Ver el canal y su paquete actual	Herencia del rol de aplicación
Historial	Ver el historial de asignación de paquetes	Herencia del rol de aplicación
Asociar paquete	Establecer o cambiar el paquete activo en el canal	Herencia del rol de la aplicación

Cada permiso puede configurarse para:

• Predeterminado — heredar del rol de la aplicación (por defecto)
• Permitir — conceder explícitamente, sin importar el rol de la aplicación
• Denegar — bloquear explícitamente, sin importar el rol de la aplicación

Esto te permite, por ejemplo, dar a un lector de aplicación la capacidad de asociar paquetes en el staging canal sin promoverlos a desarrollador de aplicación.

---

Jerarquía de roles

Los roles forman una jerarquía. Un rol padre hereda todos los permisos de sus hijos. Esto significa que un org_admin puede hacer todo lo que un app_admin puede, lo que a su vez puede hacer todo lo que un channel_admin puede, y así sucesivamente.

Super Admin (org_super_admin)
  └── Admin (org_admin)
        └── App Admin (app_admin)
              ├── App Developer (app_developer)
              │     └── App Uploader (app_uploader)
              │           └── App Reader (app_reader)
              ├── Bundle Admin (bundle_admin)
              │     └── Bundle Viewer (bundle_reader)
              └── Channel Admin (channel_admin)
                    └── Channel Viewer (channel_reader)

¿Cómo funciona en la práctica:

• Un Administrador a nivel de organización puede hacer todo lo que un Administrador de Aplicación puede, en cada aplicación de la organización.
• Un Administrador de Aplicación en una aplicación específica puede hacer todo lo que un Administrador de Canal puede, en cada canal de esa aplicación.
• Un Desarrollador de Aplicación puede hacer todo lo que un Subidor de Aplicación puede, más aún.

La jerarquía solo fluye hacia abajo — una channel_admin Nunca obtiene permisos de nivel de organización, incluso si también tiene un rol de nivel de aplicación.

---

Grupos

En lugar de asignar roles a cada usuario individualmente, puedes crear grupos y asignar roles al grupo. Cada miembro del grupo hereda automáticamente esos roles.

Cómo funcionan los grupos

• Un grupo pertenece a una organización — no puede abarcar varios orgs.
• Los grupos pueden contener asignaciones de roles en any alcance: org, app, canal, o paquete. Por ejemplo, un grupo puede asignarse el Desarrollador de Aplicación rol en la aplicación A y el Administrador de Canal rol en el staging canal de la aplicación B.
• Cuando se evalúan los permisos de un usuario, todas sus pertenencias de grupo se resuelven de manera transparente. Si alguno de sus grupos concede el permiso requerido, se permite el acceso.
• Un usuario puede pertenecer a grupos múltiplesy permisos de todos los grupos son acumulativos.
• Sólo se aplican permisos basados en grupos a principales de usuario — las API claves no heredan roles de grupo.

Cuándo usar grupos

Escenario	Sin grupos	Con grupos
5 ingenieros de pruebas necesitan acceso de Desarrollador a 3 aplicaciones	15 vinculaciones de roles individuales	1 grupo + 3 vinculaciones de roles
Alguien se une al equipo de QA	Agregar 3 vinculaciones de rol manualmente	Agregarlos al grupo
Alguien se va del equipo de QA	Eliminar 3 vinculaciones de rol manualmente	Eliminarlos del grupo

Gestionar grupos a través de API

Todas las endpoints de grupo requieren autenticación y se sirven bajo /private/groups.

Listar grupos

curl -X GET "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>"

Requiere org.read_members permiso.

Crear un grupo

curl -X POST "https://api.capgo.app/private/groups/<ORG_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Quality assurance engineers"
  }'

Requiere org.update_user_roles permiso (Administrador super o Administrador).

Actualizar un grupo

curl -X PUT "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "QA Team",
    "description": "Updated description"
  }'

Eliminar un grupo

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>" \
  -H "authorization: <API_KEY>"

Eliminar un grupo también elimina todas sus vinculaciones de rol. Los miembros no se eliminan de la organización.

Lista de miembros del grupo

curl -X GET "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>"

Agregar un miembro a un grupo

curl -X POST "https://api.capgo.app/private/groups/<GROUP_ID>/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "<USER_UUID>" }'

El usuario ya debe ser miembro de la organización. Agregar un miembro existente es una operación sin efecto.

Quitar un miembro de un grupo

curl -X DELETE "https://api.capgo.app/private/groups/<GROUP_ID>/members/<USER_UUID>" \
  -H "authorization: <API_KEY>"

Nota

Para asignar un rol a un grupo, utilice los vinculados de rol API con principal_type: "group" y principal_id establezca en la UUID del grupo.

---

Asignar roles mediante API

Lista de miembros

curl -X GET "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "<ORG_ID>" }'

Respuesta:

[
  {
    "uid": "user-uuid",
    "email": "alice@example.com",
    "image_url": "https://...",
    "role": "org_admin",
    "is_tmp": false
  }
]

Invitar a un miembro

curl -X POST "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com",
    "invite_type": "org_admin"
  }'

Valores admitidos para invite_type:

Valor	Rol asignado
org_super_admin	Administrador principal
org_admin	Administrador
org_billing_admin	Gerente de facturación
org_member	Miembro

Eliminar a un miembro

curl -X DELETE "https://api.capgo.app/organization/members" \
  -H "authorization: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "<ORG_ID>",
    "email": "bob@example.com"
  }'

---

Asignando roles a través de CLI

Listar organizaciones

npx @capgo/cli organization list --apikey <API_KEY>

Listar miembros

npx @capgo/cli organization members <ORG_ID> --apikey <API_KEY>

Nota

El CLI actualmente admite la lista de miembros. Para invitar a miembros o cambiar roles de manera programática, utilice los puntos finales API arriba mencionados.

---

Roles personalizados

Los roles incorporados cubren la mayoría de las estructuras de equipo. La creación de roles personalizados está en nuestra ruta de desarrollo — si este es algo que necesita su equipo, háganos llegar. Su caso de uso ayudará directamente a priorizar esta función.

Siga adelante desde la Referencia de Control de Acceso

Si está utilizando Referencia de Control de Acceso para planificar la consola y las operaciones API, conecte con API Resumen para los detalles de implementación en API Resumen, Introducción para los detalles de implementación en Introducción, API Claves para los detalles de implementación en API Claves, Dispositivos para los detalles de implementación en Dispositivos, y Paquetes para los detalles de implementación en Paquetes.