Referencia de control de acceso

Capgo utiliza control de acceso basado en roles (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

Todos los roles pertenecen a un ámbito que determina qué recurso concede acceso.

Ámbito	Aplica a	Ejemplo de uso
Uso de ejemplo	La organización completa y todos sus aplicativos	Tu cofundador obtiene Super Administrador; tu contable obtiene Administrador de Facturación
App	Una aplicación única y sus canales	A contractor working on one app gets App Developer
Channel	A un canal 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 App A y un rol diferente en App 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 Súper	org_super_admin	Equivalente a propietario. Control total incluyendo eliminar la organización, gestionar facturación y transferir aplicaciones. Se concede automáticamente al creador de la organización.
Administrador	org_admin	Administración completa — gestionar miembros, aplicaciones, canales. No se puede eliminar la organización, actualizar facturación, transferir aplicaciones o promover usuarios a Administrador principal.
Gerente de facturación	org_billing_admin	Acceso solo a facturación: ver y actualizar información de facturación, facturas e historial de auditoría de facturación. Sin acceso a aplicaciones o miembros.
Miembro	org_member	Acceso de solo lectura a la organización y todas sus aplicaciones.

Matriz de permisos de organización

Permiso	Descripción	Administrador Súper	Administrador	Gerente de facturación	Miembro
org.read	Ver la organización	✅	✅	✅	✅
org.update_settings	Edit org name, logo, management email	✅	✅	❌	❌
org.delete	Eliminar la organización de forma permanente	✅	❌	❌	❌
org.read_members	Ver la lista de miembros	✅	✅	❌	✅
org.invite_user	Invitar nuevos miembros	✅	✅	❌	❌
org.update_user_roles	Cambiar roles de miembros (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 registro de actividad de la organización	✅	✅	❌	❌
org.read_billing_audit	Ver registro de auditoría específico de facturación	✅	✅	✅	❌

Nota

Roles de organización heredan todos los permisos de las roles de la aplicación, canal y paquete que se encuentran debajo de ellos en la jerarquía. Super Administrador puede hacer todo lo que un App Admin o Administrador de Canal puede hacer, en todas las aplicaciones y canales.

---

App roles

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

Rol	Nombre interno	Descripción
App Admin	app_admin	Control total de una aplicación — canales, dispositivos, roles de usuario para la aplicación. No puede eliminar ni transferir la aplicación (aquellas son operaciones de nivel de organización).
Desarrollador de Aplicación	app_developer	Subir paquetes, administrar dispositivos, desencadenar compilaciones nativas, actualizar configuraciones de canal. Sin eliminación, sin cambios en configuraciones de aplicación, sin creación de canal.
Subidor de Aplicación	app_uploader	Acceso de lectura + subir nuevas versiones de paquetes.
App Reader	app_reader	Solo lectura — estadísticas, paquetes, canales, registros, dispositivos.
App Preview	app_preview	Ciclo de vida de vista previa organización- y aplicación-vinculado: subir un paquete y crear un canal de vista previa. Crear ese canal concede automáticamente derechos de ciclo de vida solo para él.

Matriz de permisos de Aplicación

Permiso	Descripción	App Admin	Desarrollador de Aplicación	Subidor de Aplicación	App Reader
app.read	Ver detalles de la aplicación, estadísticas y metadatos	✅	✅	✅	✅
app.update_settings	Editar configuración de la aplicación	✅	❌	❌	❌
app.read_bundles	Ver 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 lista de dispositivos	✅	✅	✅	✅
app.build_native	Desencadenar una construcción nube nativa	✅	✅	❌	❌
app.read_audit	Ver registro de actividad de nivel de aplicación	✅	✅	✅	✅
app.update_user_roles	Asignar roles de aplicación	✅	❌	❌	❌
bundle.delete	Eliminar un paquete	✅	❌	❌	❌

Nota

app.delete y app.transfer are operaciones de nivel de organización — only org_super_admin Conjunto de permisos de vista de aplicación

Permiso de vista previa de la aplicación

Usar App Preview (app_previewPara una clave de CI vinculada a la organización y la 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 la vinculación solo concede estos permisos de nivel de aplicación:

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

Cuando una clave de vista previa de App crea un canal, Capgo asigna automáticamente a esa clave una subclave channel_preview para el nuevo canal solo:

Permiso	Permite
channel.read	Leer el canal creado por el key
channel.promote_bundle	Establecer la carga de bundle subida por el key en ese canal
channel.delete	Borrar ese canal

Porque app_preview retiene app.read, el key puede enumerar metadatos de canal en la aplicación seleccionada. La vinculación de hijo automática es una gestión límite: no concede mutaciones de ciclo de vida para un canal que el key 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 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-bundleNo puede realizar esas acciones con un canal predeterminado principal, un canal de clave de vista previa o un paquete de otra clave.

It does not include app.update_settings, la gestión de dispositivos o roles channel.update_settings, channel.rollback_bundle, la gestión de dispositivos forzada o genérica bundle.delete.

Advertencia

Todos los enlaces de vista previa de aplicación permanecen vinculados a la organización propietaria de la aplicación seleccionada. El rol omite un rol organizativo; no elimina la asociación de organización. Revocar o expirar el enlace de la aplicación elimina el acceso de ciclo de vida efectivo de la clave.

---

Roles de canal

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

Nota

Los roles de canal están actualmente disponibles vía 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 permisos de canal de sobreescribir en lugar de 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	Leído — canal actual, historial, dispositivos forzados, registro de auditoría.
Vista previa de canal	channel_preview	Asignado por el sistema al clave App Preview que creó el canal: leer, promover su propio paquete y eliminar ese canal.

Matriz de permisos de canal

Permiso	Descripción	Administrador de canal	Vista de canal	Vista previa de canal
channel.read	Ver el canal y su paquete actual	✅	✅	✅
channel.update_settings	Editar ajustes del canal (tornillos de plataforma, política de actualización…)	✅	❌	❌
channel.delete	Eliminar 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	Volver 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

Limitado a una versión de paquete única. Raramente necesario — la mayoría de los equipos utilizan roles de aplicación en su lugar.

Nota

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

Rol	Nombre interno	Descripción
Administrador de paquete	bundle_admin	Lea, actualice los metadatos y elimine un paquete específico.
Vista de paquete	bundle_reader	Acceso de lectura a un paquete específico.

---

Permisos de canal que superan (Consola)

En la consola, el acceso al canal se determina por defecto por el rol de la aplicación del usuario. Para un control más detallado, puedes superar permisos de canal específicos por usuario o grupo sin cambiar su rol de aplicación.

Se configuran las sobrescripciones desde la aplicación Acceso 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
Leer	Ver el canal y su paquete actual	Herencia de rol de aplicación
Historial	Ver el historial de asignación de paquetes	Herencia de rol de aplicación
Asociar paquete	Establecer o cambiar el paquete activo en el canal	Herencia de rol de aplicación

Cada permiso se puede configurar a:

• Español /es/docs/aplicación web/roles de organización/
• Allow — heredar del rol de la aplicación (el predeterminado)
• Permitir — otorgar explícitamente, sin importar el rol de la aplicación

Este te permite, por ejemplo, dar a un lector de Aplicación la capacidad de asociar conjuntos en el staging — bloquear explícitamente, sin importar el rol de la aplicación

---

Estructura jerárquica de roles

Roles forman una jerarquía. Un rol padre Sección titulada “Jerarquía de roles” 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 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 pueden hacer en el nivel de la organización App Admin puede, en cada aplicación de la organización.
• Un App Admin 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 Cargador de Aplicación puede, además de más.

La jerarquía solo fluye hacia abajo — un channel_admin no gana permisos de nivel de organización, incluso si también posee un rol de nivel de aplicación.

---

Grupos

En lugar de asignar roles a cada usuario individualmente, puede 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 varias orgs.
• Los grupos pueden tener vinculaciones de roles en cualquier ámbito: organización, aplicación, canal o paquete. Por ejemplo, un grupo puede ser asignado el rol de Desarrollador de Aplicación rol en App 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últiples, y los permisos de todos los grupos son adicionales.
• Permisos solo se aplican a grupos principios de usuario --- API no heredan roles de grupo.

¿Cuándo usar grupos

Escenario	Sin grupos	Con grupos
5 QA engineers need Developer access to 3 apps	15 vinculaciones de roles individuales	1 grupo + 3 vinculaciones de roles
Alguien se une al equipo de pruebas	Agregar 3 vinculaciones de roles manualmente	Agregarlos al grupo
Alguien deja el equipo de QA	Eliminar 3 vinculaciones de roles manualmente	Eliminarlos del grupo

Administrar grupos mediante API

Todos los puntos finales de grupo requieren autenticación y se sirven bajo /private/groups.

Lista de 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 Súper o Admin).

Administrador

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"
  }'

Borrar un grupo

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

Borrar un grupo elimina también 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 debe ya ser miembro de la organización. Agregar un miembro existente es una operación sin efecto.

Quitar a 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 establecer a la 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	Administrador Súper
org_admin	Administrador
org_billing_admin	Gerente de facturación
org_member	Miembro

Eliminar 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

Lista de organizaciones

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

Lista de miembros

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

Nota

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

---

Roles personalizados

Los roles integrados cubren la mayoría de las estructuras de equipo. La creación de roles personalizados está en nuestro plan de ruta — si su equipo necesita esto, contacte con nosotrosSu 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 operaciones de panel de control y API conéctelo con API Overview 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 Bundles para los detalles de implementación en Paquetes.