Claves de API

Las claves de API usan control de acceso basado en roles (RBAC). Una clave puede tener un rol para toda la organización, bindings específicos de una app, o ambos. Cada binding de app permanece asociado a la organización propietaria de esa app. Para aplicar el principio de mínimo privilegio, limita una clave a apps concretas en lugar de asignarle un rol a nivel de organización.

¿Dónde se gestionan las claves de API?

Navega a Configuración > Organización > Claves API en console.capgo.app/settings/organization/api-keys.

La página muestra dos secciones:

• Claves RBAC — Claves con roles asignados (recomendado). Estas claves utilizan el nuevo sistema de permisos basado en roles.
• Claves Legacy — Claves antiguas que utilizan el sistema simple basado en modos (read, upload, write, all) sin roles asignados.

¿Cómo crear una nueva clave de API?

1. Haz clic en ”+” botón en la parte superior de la tabla de claves RBAC.

2. Completa la Información de la clave:

   • Nombre (obligatorio) — Una etiqueta descriptiva para la clave (por ejemplo, “CI/CD Deploy” o “Monitoring Read-Only”).
   • Crear clave segura (opcional) — Si se marca, la clave se hashea en el servidor. La clave en texto plano se muestra solo una vez tras su creación y no podrá recuperarse después.
   • Establecer fecha de expiración (opcional) — Selecciona una fecha a partir de la cual la clave dejará de funcionar. Algunas organizaciones aplican caducidad obligatoria mediante políticas.

3. Elige el alcance de la clave:

   • Acceso a toda la organización — Selecciona un Rol de la organización para definir los permisos base en toda la organización. Los roles disponibles dependen de tu nivel de rol:
     • Ninguno — Sin acceso a toda la organización.
     • Miembro — Acceso de lectura básico a la organización.
     • Administrador — Acceso administrativo total a la organización y todas sus apps.
   • Acceso solo a apps — Activar Limitar esta clave a apps seleccionadasCada vinculación de app permanece ligada a la organización propietaria; este modo solo omite un rol de RBAC a nivel de organización.

4. Si la key necesita crear organizaciones mediante el API público, activa Permitir crear organizaciones.

   Esto añade el global org.create permiso global. La key también requiere un org_admin o org_super_admin binding. En el dashboard, seleccionando Administrador crea el org_admin vínculo. Cuando esta clave crea una nueva organización, Capgo asigna automáticamente la clave como Super Admin en esa nueva organización.

5. Para dar acceso a una app:

   • Cuando Limitar esta clave a apps seleccionadas está activado, elige una organización en Organizaciones para filtrar apps para ver sus apps. Los vínculos de las apps seleccionadas siguen asociados a sus organizaciones; este filtro no otorga acceso a toda la organización.
   • Haz clic ”+ Añadir app”, selecciona una o más apps y asigna un rol a cada una:
     • Lector de app — Acceso de solo lectura a la app.
     • Uploader de app — Puede subir nuevos bundles.
     • Desarrollador de app — Puede subir bundles, gestionar dispositivos, iniciar native builds y actualizar la configuración de canales.
     • Admin de app — Acceso completo a la app.
     • Preview de app — Vista previa del ciclo de vida CI/CD: sube un bundle y crea un canal de vista previa. El canal recibe derechos de ciclo de vida automáticos y limitados al canal solo para esta clave.

6. Haz clic “Crear”.

7. Si marcaste Crear clave segura, se muestra un modal con la clave en texto plano. Cópiala de inmediato — no se puede recuperar después de cerrar el modal.

Usa una clave de App Preview para workflows de preview

Usa Preview de app para CI que crea un canal de preview temporal y no público, sube y promueve un bundle, y luego elimina tanto el canal como el bundle. No tiene acceso al ciclo de vida de un canal default o main existente.

1. Crea una clave RBAC y habilita Limitar esta clave a apps seleccionadas.
2. En Organizaciones para filtrar apps, selecciona la organización para ver sus apps; cada app seleccionada seguirá asociada a su organización.
3. Añade solo la app o apps que uses para despliegues de preview.
4. Selecciona Preview de app para cada app seleccionada.
5. Crea una clave segura, establece una fecha de expiración si es necesario y guárdala en tu gestor de secretos de CI.

Este modo de solo apps seleccionadas omite un rol a nivel de organización; no necesitas elimina la asociación con la organización. Cada app_preview binding permanece limitado a su app seleccionada y a la organización dueña de dicha app.

Conceder	Permisos y límites
app_preview en la app seleccionada	app.read, app.read_bundles, app.upload_bundle, y app.create_channel.
Automático channel_preview vinculación	Cuando esta clave crea un canal, Capgo le otorga automáticamente a la clave channel.read, channel.promote_bundle, y channel.delete solo para ese canal.

app_preview mantiene app.read, por lo que la clave puede enumerar metadatos de canales en la app seleccionada. La vinculación automática de hijos es un límite de boundary: no otorga mutaciones de ciclo de vida para canales que la clave no creó.

Capgo también registra qué clave de App Preview subió un bundle. La clave solo puede establecer su propio bundle en cada canal de preview que cree y puede limpiar ese par en conjunto. No recibe un binding de canal para un canal por defecto o principal existente, un canal creado por otra clave de preview ni el bundle de otra clave.

Para un job de CI típico, usa un nombre de canal único por cada pull request:

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_API_KEY" \
  --delete-bundle \
  --success-if-not-found

Para un nuevo canal, bundle upload --channel crea el canal, sube el bundle y lo promociona en un solo flujo. El último comando usa una ruta de limpieza atómica restringida: solo tiene éxito cuando la clave es dueña del canal de preview y de su bundle vinculado y no compartido. Preview de app sigue sin tener permisos generales bundle.delete, por lo que no puede eliminar un bundle arbitrario.

Precaución

Usa un nuevo canal pr-<number> no público. No pases --default, --self-assign, opciones de rollout o --delete-linked-bundle-on-upload a este workflow. Una Preview de app key no puede promover, eliminar o cambiar un canal default/main existente, el canal de otra preview key o el bundle de otra key. Revocar o expirar el app binding también elimina el acceso efectivo al ciclo de vida de la key.

Consulta la Referencia de control de acceso para ver el límite completo.

¿Cómo gestionar (editar) una key de API?

Haz clic en wrench icon (Gestionar) en cualquier clave RBAC de la lista. Esto abre la página de detalles de la clave, donde puedes:

• Cambiar la clave nombre,.
• Actualiza el rol de organización.
• Activar o desactivar Permitir crear organizaciones cuando la clave tiene un rol de organización Admin.
• Añadir, eliminar o cambiar roles por app.

Haz clic “Guardar cambios” al terminar.

¿Cómo regenerar una clave API?

Para regenerar el valor secreto de una clave API, haz clic en el icono de refrescar (Regenerar) en cualquier clave de la lista.

Aparecerá un diálogo de confirmación. Tras confirmar:

• Para claves seguras (hasheadas): Se genera una nueva clave en texto plano que se muestra una sola vez en un modal. Cópiala de inmediato.
• Para claves simples: El valor de la clave se regenera en el servidor.

Cualquier integración que use el valor de la clave anterior dejará de funcionar inmediatamente.

¿Cómo eliminar una clave API?

Haz clic en icono de papelera (Eliminar) en cualquier clave de la lista. Confirma la eliminación en el diálogo.

La clave se revoca inmediatamente: cualquier solicitud que la use fallará.

Claves heredadas

Si ves claves en la Claves legacy sección (claves sin asignación de roles), estas usan el antiguo sistema de permisos basado en modos (read, upload, write, all). Siguen funcionando, pero no se benefician de los permisos granulares de RBAC.

Las claves legacy se pueden regenerar y eliminar desde la lista, pero no se pueden editar para añadir roles RBAC. Recomendamos crear nuevas claves RBAC y eliminar las legacy cuando sea posible.

Si necesitas gestionar claves legacy directamente, aún puedes acceder a ellas en console.capgo.app/dashboard/apikeys. Esta página está obsoleta y se eliminará en una futura actualización.

Continuar con las Keys de API

Si estás usando Claves de API 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.