API Claves

Las API 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 API claves?

Navegue a Ajustes > 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 Legado — Claves más antiguas que utilizan el sistema de modo simple (read, upload, write, allsin asignaciones de rol.

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 rótulo descriptivo para la clave (por ejemplo, “Despliegue CI/CD” o “Lectura de Monitoreo”).
   • Crear clave segura (opcional) — Cuando se marca, la clave se cifra en el lado del 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) — Elija una fecha después de la cual la clave deja de funcionar. Algunas organizaciones imponen una expiración obligatoria a través de la política.

3. Elija el alcance de la clave:

   • Acceso organizativo en toda la organización — Seleccione un Rol de organización para definir permisos de base en toda la organización. Los roles disponibles dependen del nivel de su propio rol:
     • Ninguno — Sin acceso organizativo en toda la organización.
     • 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 para aplicaciones — Habilitar Limitar esta clave a aplicaciones seleccionadas. Cada 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 público, habilite Permitir crear organizaciones.

   Esto agrega la org.create permiso global. La clave también necesita un rol organizativo-scoped org_admin o org_super_admin vinculación. 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. Las vinculaciones de aplicaciones seleccionadas permanecen asociadas a sus organizaciones propietarias; este filtro no otorga acceso organizacional de amplio alcance.
   • Haga clic + Agregar Aplicación, selecciona una o varias aplicaciones, luego asigna un rol a cada una:
     • Lector de Aplicación — Acceso solo de 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.
     • Administrador de Aplicación — Acceso completo a la aplicación.
     • Previsualización de Aplicación — Previsualiza el ciclo de vida de CI/CD: sube un paquete y crea 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 marcado Crear una clave de texto seguro, se muestra una ventana emergente con la clave en texto plano. Copiarla inmediatamente — no se puede recuperar después de cerrar la ventana emergente.

Utilice una clave de App Preview para flujos de trabajo de vista previa

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

1. Crear una clave de RBAC y habilitar Limitar esta clave a aplicaciones seleccionadas.
2. De 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 la aplicación o aplicaciones utilizadas para despliegues de vista previa.
4. Seleccionar Vista previa de la aplicación para cada aplicación seleccionada.
5. Crear una clave segura, establecer una fecha de vencimiento cuando sea apropiado y almacenarla en tu administrador de secretos de CI.

Este modo de solo aplicaciones seleccionadas omite un rol organizativo en general; no eliminar la asociación de la organización. Cada app_preview vinculación permanece en el ámbito de la aplicación seleccionada y esa aplicación pertenece a la organización propietaria.

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 retiene app.read, por lo tanto, el key puede enumerar los metadatos del canal en la aplicación seleccionada. La vinculación automática de hijos es un gestión límite: no concede mutaciones de ciclo de vida para los canales que el key no creó.

Capgo también registra qué key de App Preview subió un paquete. El key puede establecer solo su propio paquete en cada canal de vista previa que crea y puede eliminar esa pareja juntos. No recibe una vinculación de canal para un canal predeterminado o principal existente, un canal creado por otra key de vista previa o un paquete de otra key.

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 el key es dueño del canal de vista previa y su paquete vinculado, no compartido. App Preview todavía no tiene funcionalidad general bundle.deleteno puede eliminar un paquete arbitrario.

Precaución

Utilice un nuevo canal no público. pr-<number> No pase --default, --self-assign, opciones de lanzamiento, o --delete-linked-bundle-on-upload a este flujo de trabajo. Un Vista previa de la aplicación no puede promover, eliminar o cambiar un canal existente predeterminado/principal, un canal de vista previa de otra clave, o un paquete de otra clave. Revocar o vencer la vinculación de la aplicación también elimina el acceso de ciclo de vida efectivo de la clave.

Consulte la Referencia de Control de Acceso para el límite completo.

How to manage (edit) an API key?

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

• Cambiar el nombre de la clave Actualizar el.
• rol de organización Habilitar o deshabilitar.
• Permitir crear organizaciones cuando la clave tenga un rol de organización administrador. __CAPGO_KEEP_0__
• Agregar, eliminar o cambiar roles por aplicación.

Haga clic “Guardar cambios” cuando esté listo.

¿Cómo regenerar una clave API?

Para regenerar el valor secreto de una clave API, haga 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:

• For claves (llaves hashadas) seguras: Se genera una nueva llave de texto plano y se muestra una vez en una ventana emergente. Copiarla inmediatamente.
• For llaves planas: El valor de la llave se regenera en el lado del servidor.

Cualquier integración que utilice el valor de la llave antigua dejará de funcionar inmediatamente.

¿Cómo eliminar una llave API?

Haga clic en el ícono de la papelera (Eliminar) en cualquier tecla de la lista. Confirme la eliminación en el diálogo.

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

Claves obsoletas

Si ve claves en el Claves obsoletas sección (claves sin asignaciones de rol), estas utilizan el sistema de permisos basado en modo (read, upload, write, all). Aún funcionan pero no benefician de los permisos de RBAC finamente detallados.

Las claves obsoletas pueden ser regeneradas y eliminadas de la lista, pero no pueden ser editadas para agregar roles de RBAC. Recomendamos crear nuevas claves de RBAC y eliminar claves obsoletas cuando sea posible.

Si necesita gestionar claves obsoletas directamente, aún puede acceder a ellas en console.capgo.app/dashboard/apikeysEsta página está descontinuada y se eliminará en una actualización futura.

Siga desde API Claves

Si está utilizando API Claves para planificar la consola y API operaciones, conecte con API Resumen 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 el detalle de implementación en Dispositivos, y Paquetes para el detalle de implementación en Paquetes.