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 Heredadas — Claves más antiguas que utilizan el sistema basado en 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 los Información de la clave:

   • Nombre (obligatorio) — Un etiqueta descriptiva para la clave (por ejemplo, “Despliegue CI/CD” o “Lectura Solo 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 a partir de la cual la clave dejará de funcionar. Algunas organizaciones imponen la expiración obligatoria mediante política.

3. Seleccione el alcance de la clave:

   • Acceso organizativo — Seleccione un Rol de organización para definir permisos de base a lo largo de la organización. Los roles disponibles dependen del nivel de su propio rol:
     • Ninguno — Sin acceso organizativo en general.
     • 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 aplicación que la posee; este modo omite solo un rol de RBAC organizativo en general.

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

   Esta agrega la autorización global. org.create La clave también necesita una organización con alcance. org_admin o org_super_admin La clave también necesita una organización con alcance. o La clave también necesita una organización con alcance. org_admin binding. When this key creates a new organization, Capgo automatically assigns the key as Super Admin on that new organization.

5. La clave también necesita una organización con alcance.

   • Crear la vinculación. Admin Crear la vinculación. Para conceder acceso a la aplicación: Cuando se habilita Limitar esta clave a aplicaciones seleccionadas, elija una organización bajo Organizaciones para filtrar aplicaciones. para revelar sus aplicaciones. Las vinculaciones de la aplicación seleccionada permanecen asociadas con sus organizaciones propietarias; este filtro no concede acceso organizacional en toda la medida.
   • Haz clic ”+ Agregar Aplicación”, selecciona una o más aplicaciones, luego asigna un rol a cada:
     • Leer Aplicación — Acceso de solo lectura a la aplicación.
     • Subir Aplicación — Puede subir nuevos conjuntos de paquetes.
     • Desarrollador de Aplicación — Puede subir conjuntos de paquetes, gestionar dispositivos, desencadenar compilaciones nativas y actualizar ajustes de canal.
     • Administrador de Aplicación — Acceso completo a la aplicación.
     • Vista de la aplicación — Vista la vida cíclica de CI/CD: subir un paquete y crear un canal de vista previa. El canal recibe derechos de vida cíclica solo para este canal.

6. Hacer clic Crear.

7. Si has marcado Crear una clave segura, se muestra un diálogo con la clave en texto plano. Copiarlo inmediatamente — no se puede recuperar después de cerrar el diálogo.

Utiliza una clave de vista previa de la aplicación para flujos de trabajo de vista previa

Utilice Vista previa de la aplicación para CI que crea un canal de vista previa temporal y no público, sube y promueve un paquete, y 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. 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 la aplicación o aplicaciones utilizadas para despliegues de vista previa.
4. Seleccione Vista previa de la aplicación para cada aplicación seleccionada.
5. Crear una clave segura, establecer una fecha de caducidad cuando sea apropiado y almacenarla en tu administrador de secretos de CI.

Este modo solo para aplicaciones omitirá un rol organizativo; no no elimina la asociación de la organización. Cada app_preview vinculación permanece limitada a su aplicación seleccionada y esa aplicación de la organización propietaria.

Otorgar	permisos y límites
app_preview en la aplicación seleccionada	app.read, app.read_bundles, app.upload_bundle, y app.create_channel.
vinculación automática channel_preview vinculación	Cuando esta clave crea un canal, Capgo da automáticamente la clave channel.read, channel.promote_bundley channel.delete para ese canal solo.

app_preview retiene app.read, por lo tanto, la clave puede enumerar metadatos de 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 canales que la clave no creó.

Capgo también registra qué clave de vista previa de la aplicación subió un paquete. La clave puede establecer solo su propio paquete en cada canal de vista previa 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 previa 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 previa y su paquete vinculado, no compartido. Vista de la aplicación todavía no tiene general bundle.delete, por lo tanto no 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. Una Vista de la aplicación clave no puede promover, eliminar o cambiar un canal existente predeterminado/principal, un canal de otra clave de vista previa 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 el Referencia de Control de Acceso para el límite completo.

Cómo gestionar (editar) una API clave?

Haga clic en el ícono de llave inglesa (Administrar) en cualquier clave 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.
• icon Permitir la creación de organizaciones cuando la clave tiene un rol de organización de administrador.
• Agregar, eliminar o cambiar roles por aplicación.

Hacer 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:

• Para claves seguras (hasheadas): Se genera y muestra una nueva clave de texto plano en una ventana emergente. Copiarla inmediatamente.
• Para claves de texto plano: El valor de la clave se regenera en el servidor.

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

Cómo eliminar una clave API?

Click 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 obsoletas

Si ve claves en la Claves Obsoletas sección (claves sin asignaciones de roles), estas utilizan el sistema de permisos basado en modo más antiguo (read, upload, write, allLas claves obsoletas aún funcionan, pero no aprovechan las permisos de RBAC finamente detallados.

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

If necesitas administrar claves legadas directamente, puedes acceder a ellas en consola.capgo.app/dashboard/apikeys. Esta página está descontinuada y se eliminará en una actualización futura.

Sigue adelante desde Claves API

Si estás utilizando Claves API para planificar la consola y las operaciones de API, conecta con API Overview para obtener detalles de implementación en API Overview, Introducción para obtener detalles de implementación en Introducción, API Claves para el detalle 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.