Referencia de control de acceso

Capgo utiliza control de acceso basado en roles (RBAC) para gestionar los permisos de cada miembro del equipo. Los roles se organizan por alcance — desde toda la organización hasta un solo bundle.

Para un recorrido visual sobre cómo gestionar miembros en el dashboard, consulta Organización.

---

Role scopes

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

Alcance	Se aplica a	Ejemplo de uso
Organización	Toda la organización y todas sus apps	Tu cofundador recibe Super Admin; tu contable recibe Billing Manager
app	Una sola app y sus canales	Un contratista en una app tiene App Developer
Canal	Un solo canal dentro de una app	Un QA engineer solo gestiona el staging canal
Bundle	Una sola versión de bundle	Un reviewer necesita acceso de lectura a un release

Un miembro puede tener un rol por cada scope — por ejemplo, un rol de org, un rol en la App A y otro en la App B.

---

Roles de la organización

Estos roles se asignan al invitar a un miembro. Otorgan acceso a toda la organización.

Rol	Nombre interno	Descripción
Superadministrador	org_super_admin	Equivalente a Owner. Control total, incluyendo borrar la org, gestionar el billing y transferir apps. Se asigna automáticamente al creador.
Administrador	org_admin	Administración total: gestiona miembros, apps y channels. No puede borrar la org, actualizar el billing, transferir apps o promover usuarios a Super Admin.
Gestor de facturación	org_billing_admin	Acceso solo a billing: ver y actualizar info de billing, facturas y logs de auditoría. Sin acceso a apps o miembros.
Miembro	org_member	Acceso de solo lectura a la org y todas sus apps.

Matriz de permisos de la organización

Permiso	Descripción	Superadministrador	Administrador	Gestor de facturación	Miembro
org.read	Ver la organización	✅	✅	✅	✅
org.update_settings	Editar nombre, logo y email de gestión de la org	✅	✅	❌	❌
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 (un Admin no puede promover a Super Admin — 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 el log de actividad de la organización	✅	✅	❌	❌
org.read_billing_audit	Ver el registro de auditoría de facturación	✅	✅	✅	❌

Nota

Los roles de organización heredan todos los permisos de los roles de app, channel y bundle que se encuentran debajo en la jerarquía. Un Superadministrador puede hacer todo lo que un Admin de app o Admin de canal puede hacer, en todas las apps y canales.

---

Roles de la app

Limitado a una sola app. Úsalos cuando un miembro del equipo deba trabajar solo en una app y no en toda la organización.

Rol	Nombre interno	Descripción
Admin de app	app_admin	Control total de una app: canales, dispositivos y roles de usuario. No puede eliminar ni transferir la app (operaciones a nivel de organización).
Desarrollador de app	app_developer	Sube bundles, gestiona dispositivos, lanza Native Build y actualiza la configuración de canales. Sin eliminar nada, sin cambiar ajustes de la app ni crear canales.
Uploader de app	app_uploader	Acceso de lectura + subida de nuevas versiones de bundles.
Lector de app	app_reader	Solo lectura: estadísticas, bundles, canales, logs y dispositivos.
Preview de app	app_preview	Ciclo de vida de CI de preview vinculado a la organización y la app: sube un bundle y crea un canal de preview. Al crear ese canal, se otorgan automáticamente derechos de ciclo de vida solo para él.

Matriz de permisos de la app

Permiso	Descripción	Admin de app	Desarrollador de app	Uploader de app	Lector de app
app.read	Ver detalles, stats y metadatos de la app	✅	✅	✅	✅
app.update_settings	Editar configuración de la app	✅	❌	❌	❌
app.read_bundles	Ver la lista de bundles subidos	✅	✅	✅	✅
app.upload_bundle	Subir una nueva versión del bundle	✅	✅	✅	❌
app.create_channel	Crear un nuevo channel	✅	❌	❌	❌
app.read_channels	Ver channels	✅	✅	✅	✅
app.read_logs	Ver logs de entrega de updates	✅	✅	✅	✅
app.manage_devices	Asignar, sobrescribir o desvincular dispositivos	✅	✅	❌	❌
app.read_devices	Ver la lista de dispositivos	✅	✅	✅	✅
app.build_native	Ejecutar un native cloud build	✅	✅	❌	❌
app.read_audit	Ver el log de actividad de la app	✅	✅	✅	✅
app.update_user_roles	Gestionar roles a nivel de app	✅	❌	❌	❌
bundle.delete	Eliminar un bundle	✅	❌	❌	❌

Nota

app.delete y app.transfer son operaciones a nivel de organización — solo org_super_admin puede realizarlas, sin importar los roles de la app.

Permisos de App Preview configurados

Usa Preview de app (app_preview) para una clave CI vinculada a la organización y la app que gestiona el ciclo de vida de un PR preview sin acceso amplio a la app u organización.

El app_preview este vínculo solo otorga estos permisos a nivel de app:

Permiso	Permite
app.read	Leer la app seleccionada
app.read_bundles	Leer bundles subidos
app.upload_bundle	Subir un bundle
app.create_channel	Crear un canal

Cuando una key de App Preview crea un canal, Capgo le asigna automáticamente a esa key un binding channel_preview hijo solo para el nuevo canal:

Permiso	Permite
channel.read	Leer el canal creado por la key
channel.promote_bundle	Establecer el bundle subido de la propia key en ese canal
channel.delete	Eliminar ese canal

Porque app_preview mantiene app.read, la clave puede enumerar los metadatos de canales en la app seleccionada. El binding automático de hijos es un límite de gestión: no otorga mutaciones del ciclo de vida para un canal que la clave no haya creado.

Capgo registra la clave de preview que creó cada canal y subió cada bundle. Por tanto, una clave de App Preview puede crear cada canal de preview no público que necesite, promover su propio bundle y eliminar atómicamente ese canal y ese bundle con channel delete --delete-bundle; no puede hacer esas cosas con un canal default/main existente, con el canal de otra clave de preview ni con el bundle de otra clave.

It does not include app.update_settingsla gestión de dispositivos o roles, channel.update_settings, channel.rollback_bundlela gestión de dispositivos forzados ni bundle.delete.

Precaución

la gestión genérica. Cada binding de App Preview permanece vinculado a la organización propietaria de la app seleccionada. El rol no incluye un rol para toda la organización, pero no elimina la asociación con la organización. Revocar o hacer caducar el binding de la app elimina el acceso efectivo de la clave al ciclo de vida.

---

Roles de canal

Limitados a un solo canal. Útiles para dar acceso dirigido a un canal de release específico.

Nota

Los roles de canal están disponibles actualmente solo a través de API y CLI — no hay una interfaz en el dashboard para asignarlos. channel_preview es una excepción: Capgo la crea automáticamente para una clave de App Preview cuando dicha clave crea un canal. En el dashboard, usa overrides de permisos de canal en su lugar para ajustar el acceso al canal por usuario.

Rol	Nombre interno	Descripción
Admin de canal	channel_admin	Control total de un canal: ajustes, promover/revertir bundles y gestionar dispositivos forzados.
Lector de canal	channel_reader	Solo lectura: bundle actual, historial, dispositivos forzados y logs de auditoría.
Preview de canal	channel_preview	Asignado automáticamente a la clave de App Preview que creó el canal: puede leer, promover su propio bundle y eliminar dicho canal.

Matriz de permisos de canal

Permiso	Descripción	Admin de canal	Lector de canal	Preview de canal
channel.read	Ver el canal y su bundle actual	✅	✅	✅
channel.update_settings	Editar ajustes del canal (plataformas, política de updates...)	✅	❌	❌
channel.delete	Eliminar el canal	✅	❌	✅
channel.read_history	Ver historial de asignación de bundles	✅	✅	❌
channel.promote_bundle	Establecer el bundle activo en el canal	✅	❌	✅
channel.rollback_bundle	Hacer rollback a un bundle anterior	✅	❌	❌
channel.manage_forced_devices	Forzar dispositivos específicos a este canal	✅	❌	❌
channel.read_forced_devices	Ver la lista de dispositivos forzados	✅	✅	❌
channel.read_audit	Ver el log de actividad del canal	✅	✅	❌

---

Roles de bundle

Limitados a una versión de bundle. Se usan poco; la mayoría de los equipos prefieren roles a nivel de app.

Nota

Los roles de bundle están disponibles actualmente solo a través de API y CLI — no hay una interfaz en el dashboard para asignarlos.

Rol	Nombre interno	Descripción
Administrador de Bundles	bundle_admin	Leer, actualizar metadatos y eliminar un bundle específico.
Visor de bundles	bundle_reader	Acceso de solo lectura a un bundle específico.

---

Sobrescritura de permisos de canal (Dashboard)

En el dashboard, el acceso a los canales se determina por el rol de la app del usuario por defecto. Para un control más granular, puedes sobrescribir permisos de canal específicos por usuario o grupo sin cambiar su rol en la app.

Las sobrescrituras se configuran desde la pestaña Acceso pestaña haciendo clic en el botón de permisos del canal (icono de escudo) junto a un usuario. Ver Organización — Sobrescribir permisos de canal para un recorrido visual.

Permisos sobrescribibles

Permiso	Descripción	Comportamiento por defecto
Consulta la	Ver el canal y su bundle actual	Heredado del rol de la app
Historial	Ver el historial de asignación de bundles	Heredado del rol de la app
Asociar bundle	Establece o cambia el bundle activo en el canal	Heredado del rol de la app

Cada permiso puede configurarse como:

• Predeterminado — heredar del rol de la app (por defecto)
• Permitir — otorgar explícitamente, sin importar el rol de la app
• Denegar — bloquear explícitamente, sin importar el rol de la app

Esto te permite, por ejemplo, dar a un App Reader la capacidad de asociar bundles en el staging canal sin necesidad de ascenderlo a App Developer.

---

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

• Una Administrador a nivel de organización puede hacer todo lo que un Admin de app puede, en todas las apps de la org.
• Una Admin de app en una app específica puede hacer todo lo que un Admin de canal puede, en todos los canales de esa app.
• Una Desarrollador de app puede hacer todo lo que un Uploader de app puede, y más.

La jerarquía solo fluye hacia abajo — un channel_admin usuario nunca obtiene permisos a nivel de org, aunque tenga un rol a nivel de app.

---

Grupos

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

Cómo funcionan los grupos

• Un grupo pertenece a una sola organización — no puede abarcar varias orgs.
• Los grupos pueden tener asignaciones de rol en cualquier scope: org, app, channel o bundle. Por ejemplo, a un grupo se le puede asignar el Desarrollador de app rol en la App A y el Admin de canal rol en el staging channel de la App B.
• Al evaluar los permisos de un usuario, todas sus membresías de grupo se resuelven de forma transparente. Si alguno de sus grupos otorga el permiso requerido, se permite el acceso.
• Un usuario puede pertenecer a múltiples grupos, y los permisos de todos los grupos se suman.
• Los permisos basados en grupos solo se aplican a principales de usuario — las llaves API no heredan roles de grupo.

Cuándo usar grupos

Escenario	Sin grupos	Con grupos
5 ingenieros de QA necesitan acceso de Developer a 3 apps	15 vinculaciones de roles individuales	1 grupo + 3 role bindings
Alguien se une al equipo de QA	Añadir 3 role bindings manualmente	Añadirlos al grupo
Alguien deja el equipo de QA	Eliminar 3 role bindings manualmente	Eliminarlos del grupo

Gestionar grupos mediante API

Todos los endpoints de grupos 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 (Superadministrador 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>"

Al eliminar un grupo también se eliminan todas sus asignaciones de roles. Los miembros no se eliminan de la organización.

Listar miembros del grupo

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

Añadir 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. Si el miembro ya existe, la acción no tendrá efecto.

Eliminar 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, usa los role bindings de API con principal_type: "group" y principal_id el UUID del grupo.

---

Asignar roles mediante API

Listar 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 aceptados para invite_type:

Valor	Rol asignado
org_super_admin	Superadministrador
org_admin	Administrador
org_billing_admin	Gestor 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"
  }'

---

Asignar roles mediante 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 permite listar miembros. Para invitar miembros o cambiar roles mediante código, usa los endpoints de API de arriba.

---

Roles personalizados

Los roles integrados cubren la mayoría de las estructuras de equipo. La creación de roles personalizados está en nuestro roadmap; si tu equipo lo necesita, contáctanos. Tu caso de uso nos ayudará directamente a priorizar esta funcionalidad.

Sigue con la referencia de control de acceso

Si estás usando Referencia de control de acceso para planificar las operaciones del dashboard y de API, conéctalo con Resumen de API para los detalles de implementación en API Overview, Introducción para los detalles de implementación en la Introducción, Claves de API para el detalle de implementación en API Keys, Dispositivos para el detalle de implementación en Devices, y Bundles para el detalle de implementación en Bundles.