Claves de API

Las llaves de API usan control de acceso basado en roles (RBAC). Una llave puede tener un rol para toda la organización, bindings específicos de una app, o ambos. Cada binding de app sigue asociado a la organización propietaria. Para seguir el principio de mínimo privilegio, restringe una llave a apps seleccionadas en lugar de asignar un rol a nivel de organización.

¿Dónde se gestionan las llaves de API?

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

La página muestra dos secciones:

• Claves RBAC — Keys con roles asignados (recomendado). Estas keys usan el nuevo sistema de permisos basado en roles.
• Claves heredadas — Keys antiguas que usan el sistema simple basado en modos (read, upload, write, all) sin asignación de roles.

¿Cómo crear una nueva API key?

1. Haz clic en el ”+” 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) — Al marcarlo, la clave se cifra en el servidor. Se mostrará la clave en texto plano solo una vez tras su creación y no podrá recuperarse después.
   • Establecer fecha de expiración (opcional) — Elige una fecha tras la cual la clave dejará de funcionar. Algunas organizaciones exigen la expiración obligatoria por política.

3. Elige el alcance de la clave:

   • Acceso a toda la organización — Selecciona un Rol en 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 básico de lectura a la organización.
     • Admin — Acceso administrativo total a la organización y a todas sus apps.
   • Acceso solo a apps — Habilitar Limita 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 clave debe crear organizaciones mediante el API público, habilita Permitir la creación de organizaciones.

   Esto añade el permiso org.create permiso. La clave también requiere un ámbito de organización org_admin o org_super_admin vinculación. En el dashboard, al seleccionar Admin se crea el org_admin vinculación. Cuando esta clave crea una nueva organización, Capgo asigna automáticamente la clave como Super Admin en dicha organización.

5. Para dar acceso a una app:

   • Cuando Limita esta clave a apps seleccionadas esté habilitado, elige una organización en Organizaciones para filtrar apps para ver sus apps. Los bindings de la app seleccionada siguen asociados a sus organizaciones; este filtro no otorga acceso a toda la organización.
   • Haz clic en + Añadir App, selecciona una o más apps y asigna un rol a cada una:
     • Lector de apps — Acceso de solo lectura a la app.
     • Subidor de apps — Puede subir nuevos bundles.
     • Desarrollador de apps — Puede subir bundles, gestionar dispositivos, lanzar Native Builds y actualizar la configuración de canales.
     • Admin de la app — Acceso total a la app.
     • App Preview — Previsualización del ciclo CI/CD: sube un bundle y crea un canal de preview. El canal recibe derechos de ciclo de vida automáticos y limitados a este canal solo para esta clave.

6. Haz clic en “Crear”.

7. Si marcaste Crear clave segura, se muestra la clave en texto plano. Cópiala de inmediato — no podrás recuperarla tras cerrar el modal.

Usa una clave de App Preview para flujos de preview

Usa App Preview para CI que crea un canal de preview temporal y privado, sube y promociona un bundle, y luego elimina tanto el canal como el bundle. No tiene acceso al ciclo de vida de un canal principal o por defecto.

1. Crea una clave RBAC y habilítala Limita 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 App Preview 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 el rol a nivel de organización; esto no elimina la asociación con la organización. Cada app_preview binding se mantiene limitado a su app seleccionada y a la organización dueña de dicha app.

Otorgar	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 permisos 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 del canal en la app seleccionada. La vinculación automática de hijos es un gestión límite: no otorga mutaciones de ciclo de vida para canales que la clave no haya creado.

Capgo también registra qué clave de App Preview subió un bundle. La clave solo puede configurar su propio bundle en cada canal de preview que cree y puede limpiar ese par de forma conjunta. No recibe un binding de canal para un canal principal o por defecto existente, un canal creado por otra clave de preview, o 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. App Preview todavía no tiene acceso general bundle.delete, por lo que no puede borrar un bundle arbitrario.

Atención

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

Consulta el Referencia de control de acceso para ver los límites completos.

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

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

• Cambiar el nombre de la clave nombre.
• Actualizar el rol de la organización.
• Habilitar o deshabilitar Permitir la creación de organizaciones cuando la clave tiene un rol de Admin en la organización.
• Añadir, eliminar o cambiar roles por aplicación.

Haz clic en “Guardar cambios” cuando termine.

¿Cómo regenerar una clave API?

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

Aparecerá un cuadro 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 plain keysEl valor de la clave se regenera en el servidor.

Cualquier integración que use la clave antigua dejará de funcionar inmediatamente.

¿Cómo eliminar una clave API?

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

La clave se revoca de inmediato; cualquier petición que la use fallará.

Claves legacy

Si ves claves en la Claves heredadas 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 cuentan con los permisos granulares de RBAC.

Las legacy keys 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 keys cuando sea posible.

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

Continuar desde API Keys

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