Llaves API

API las claves utilizan el control de acceso basado en roles (RBAC). Una clave puede tener un rol organizativo, vinculaciones de aplicación o ambos. Cada vinculación de aplicación permanece asociada con la organización propietaria de la aplicación. Para el privilegio mínimo, restrinja una clave a aplicaciones seleccionadas en lugar de asignar un rol organizativo.

¿Dónde se gestionan las claves API?

Navegue a Ajustes > Organización > API Claves en console.capgo.app/settings/organization/api-claves.

La página muestra dos secciones:

• Claves de RBAC — Claves con roles asignados (recomendado). Estas claves utilizan el nuevo sistema de permisos basado en roles.
• Claves Legado — Claves más antiguas que utilizan el sistema de modo simple (read, upload, write, all) sin asignaciones de roles.

¿Cómo crear una nueva API clave?

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

2. Rellene la Información de la clave:

   • Nombre (obligatorio) — Un etiqueta descriptiva para la clave (por ejemplo, “Despliegue CI/CD” o “Lectura de solo monitoreo”).
   • Crear clave segura (opcional) — Cuando se marca, la clave se cifra en el servidor. La clave en texto plano se muestra solo una vez después de la creación y no se puede recuperar más tarde.
   • Establecer fecha de expiración (opcional) — Selecciona una fecha a partir de la cual la clave dejará de funcionar. Algunas organizaciones imponen una expiración obligatoria mediante política.

3. Elige el alcance de la clave:

   • Acceso organizativo — Selecciona un Rol de la organización para definir permisos básicos a nivel de organización. Los roles disponibles dependen del nivel de tu propio rol:
     • Sin rol — Sin acceso organizativo.
     • Miembro — Acceso de lectura básico a la organización.
     • Administrador — Acceso administrativo completo a la organización y a todas sus aplicaciones.
   • Acceso solo a la aplicación — Habilitar Limitar esta clave a aplicaciones seleccionadasCada vinculación de aplicación permanece vinculada a la organización propietaria de esa aplicación; este modo omite solo un rol de RBAC organizativo.

4. Si la clave necesita crear organizaciones a través del API, habilitar Permitir crear organizaciones.

   Esta agrega la global org.create permiso. La clave también necesita un ámbito de organización org_admin ¿O org_super_admin binding. En la consola, seleccionar Admin crea la org_admin vinculación. Cuando esta clave crea una nueva organización, Capgo asigna automáticamente la clave como Super Administrador en esa nueva organización.

5. Para otorgar acceso a la aplicación:

   • Cuando Limitar esta clave a aplicaciones seleccionadas está habilitado, elija una organización bajo Organizaciones para filtrar aplicaciones para revelar sus aplicaciones. Los vinculados de aplicaciones seleccionadas permanecen asociados con sus organizaciones propietarias; este filtro no otorga acceso organización en general.
   • Haga clic Agregar Aplicaciónselect one or more apps, then assign a role to each:
     • App Reader Acceso de solo lectura a la aplicación.
     • Subidor de Aplicación — Puede subir nuevos paquetes.
     • Desarrollador de Aplicación — Puede subir paquetes, gestionar dispositivos, desencadenar compilaciones nativas y actualizar configuraciones de canal.
     • App Admin — Acceso completo a la aplicación.
     • App Preview — Previsualice el ciclo de CI/CD: subir un paquete y crear un canal de previsualización. El canal recibe derechos de ciclo de vida automáticamente, solo para este canal.

6. Haga clic “Crear”.

7. Si has verificado Crear una clave seguraUna ventana emergente muestra la clave en texto plano. Copiarla inmediatamente — no se puede recuperar después de cerrar la ventana.

Use an App Preview key for preview workflows

Utilice App Preview para CI que crea un canal temporal no público de vista previa, sube y promueve un paquete, luego elimina tanto el canal como el paquete. No tiene acceso a la vida cíclica a un canal existente predeterminado o principal.

1. Crear una clave de RBAC y habilitar Límite esta clave a aplicaciones seleccionadas.
2. Bajo Organizaciones para filtrar aplicaciones, seleccione la organización para revelar sus aplicaciones; cada aplicación seleccionada permanece asociada con su organización propietaria.
3. Agregar solo las aplicaciones utilizadas para despliegues de previsualización.
4. Seleccione App Preview para cada aplicación seleccionada.
5. Crear una clave segura, establezca una fecha de vencimiento cuando sea apropiado y almacénela en tu administrador de secretos de CI.

Este modo de solo aplicaciones seleccionadas omite un rol organizativo; no no elimina la asociación de la organización. Cada app_preview se mantiene vinculado a la aplicación seleccionada y a la organización propietaria de esa aplicación.

Grant	Permisos y límites
app_preview en la aplicación 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 da automáticamente la clave channel.read, channel.promote_bundle, y channel.delete solo para ese canal.

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

Capgo también registra qué clave de vista de la aplicación subió un paquete. La clave puede establecer solo su propio paquete en cada canal de vista que crea y puede limpiar esa pareja juntos. No recibe una vinculación de canal para un canal predeterminado o principal existente, un canal creado por otra clave de vista o un paquete de otra clave.

Para un trabajo de CI típico, utilice un nombre de canal único por solicitud de extracción:

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 paquete y lo promueve en un flujo. El último comando utiliza una ruta de limpieza atómica estrecha: solo tiene éxito cuando la clave es dueña del canal de vista previo y su paquete vinculado, no compartido. App Preview aún no tiene funcionalidad general bundle.deletepor lo tanto no puede eliminar un paquete arbitrario.

Cuidado

Utilice un nuevo canal no público. pr-<number> canal. No pasar --default, --self-assignopciones de implementación --delete-linked-bundle-on-upload an este flujo de trabajo Consulte la key cannot promote, delete, or change an existing default/main channel, another preview key’s channel, or another key’s bundle. Revoking or expiring the app binding also removes the key’s effective lifecycle access.

Ver Cómo administrar (editar) una clave __CAPGO_KEEP_0__? para la frontera completa.

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

Haga clic en el icono de llave (Administrar) en cualquier clave de RBAC de la lista. Esto abre la página de detalles de la clave donde puede:

• Cambiar el nombre de la clave Cambiar el.
• actualizar Habilitar o deshabilitar.
• Permitir crear organizaciones Permitir crear organizaciones cuando la clave tenga un rol de organización de administrador.
• roles por aplicación icono de llave inglesa.

Haz clic “Guardar cambios” terminado.

Cómo regenerar una clave API?

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

Se mostrará un diálogo de confirmación. Después de confirmar:

• Para claves (hash) seguras: Se genera y muestra una nueva clave de texto plano en una ventana emergente. Copiela inmediatamente.
• Para llaves planasLa clave de valor se regenera en el servidor.

Cualquier integración que utilice el valor de clave antiguo dejará de funcionar inmediatamente.

¿Cómo eliminar una clave API?

Haga clic en el icono de basura (Eliminar) en cualquier clave de la lista. Confirme la eliminación en el diálogo.

La clave se revoca inmediatamente — cualquier solicitud que la utilice fallará.

Claves de legado

Si ve claves en la Claves de Legado Estas claves (sin asignaciones de rol) utilizan el sistema de permisos basado en modo más antiguo.read, upload, write, allsigue funcionando pero no aprovecha las permisos de RBAC finamente detallados.

Las claves de legado se pueden regenerar y eliminar desde la lista, pero no se pueden editar para agregar roles de RBAC. Se recomienda crear claves de RBAC nuevas y eliminar claves de legado cuando sea posible.

Si necesita administrar claves de legado directamente, todavía puede acceder a ellas en console.capgo.app/panel de control/apikeysEsta página está descontinuada y será eliminada en una actualización futura.

Sigue adelante desde las API Claves

Si estás utilizando API Claves para planificar la consola y las operaciones de API Resumen de API Para la implementación detallada en API Resumen. Introduction para los detalles de implementación en la Introducción. API Claves Para los detalles de implementación en API Claves. Devices para los detalles de implementación en dispositivos. Paquetes para el detalle de implementación en Paquetes.