Pular al contenido
Capgo - Actualizaciones en vivo para aplicaciones Capacitor Capgo

API Claves

Las claves API se utilizan para autenticar solicitudes al Capgo API. Las claves son específicas de la organización y se pueden asignar roles de control de acceso RBAC para un control de acceso fino-granular. Cada clave también puede tener una fecha de caducidad opcional y se puede crear como una clave “segura” (hashada) donde el valor en texto plano solo se muestra una vez.

Usando una clave API

Título de la sección “Usando una clave API”

Utilice el encabezado de autenticación documentado por el punto final. Para solicitudes con claves API-clave, authorization Es aceptado:

Ventana de terminal
curl -H "authorization: YOUR_API_KEY" https://api.capgo.app/...

Algunos puntos finales también aceptan un encabezado de clave dedicado. Canales API acepta authorization o capgkeyo se utiliza uno de esos encabezados para la automatización de canal de previsualización.

Permisos de RBAC

Título de sección “Permisos de RBAC”

Las llaves API utilizan el mismo sistema de control de acceso basado en roles (RBAC) que las cuentas de usuario. Al crear o administrar llaves a través de la aplicación web o API, asigna roles a dos niveles:

  • Rol de organización — Define las permisos básicos de la llave en toda la organización (por ejemplo, org_admin o org_member).
  • contexto: Fragmento de texto HTML de una cadena de Capgo UI más larga (clave padre `alternatives_cta_questions`). Página/área: Comparación de alternativas de actualización en vivo de Capacitor. Papel: Parágrafo de marketing o legal largo. Visto en: página alternatives.astro. Preservar términos de producto y marca de Capgo exactamente. Clave de mensaje `alternatives_cta_questions` (Preguntas de CTA de alternativas). | Fragmento de texto HTML de una cadena de Capgo UI más larga (clave padre `appflow_cta_questions`). Página/área: Copia de marketing de comparación/migración de Appflow. Papel: Parágrafo de marketing o legal largo. Visto en: página ionic-appflow.astro. Preservar términos de producto y marca de Capgo exactamente. Clave de mensaje `appflow_cta_questions` (Preguntas de CTA de Appflow). | Fragmento de texto HTML de una cadena de Capgo UI más larga (clave padre `capwesome_cta_questions`). Página/área: Página de comparación de Capawesome. Papel: Parágrafo de marketing o legal largo. Visto en: página capwesome.astro. Preservar términos de producto y marca de Capgo exactamente. Clave de mensaje `capwesome_cta_questions` (Preguntas de CTA de Capwesome). | Fragmento de texto HTML de una cadena de Capgo UI más larga (clave padre `consulting_faq_subtitle`). Página/área: Página de servicios de consultoría. Papel: Título de sección o etiqueta. Visto en: página consulting.astro. Preservar términos de producto y marca de Capgo exactamente. Clave de mensaje `consulting_faq_subtitle` (Título de sección de FAQ de consultoría). | Página/área: Copia de marketing de comparación/migración de Appflow. Papel: Etiqueta de UI corta o elemento de navegación. Visto en: página ionic-appflow.astro, página ionic-enterprise-plugins.astro, página soluciones/ionic-enterprise-plugins.astro. Clave de mensaje `appflow_plugins_or` (O plugins de Appflow). Permisos de aplicación app_admin, app_developer, app_uploader, app_readero app_preview).

Si una clave API tiene vinculaciones de rol explícitas, solamente se evalúan esas vinculaciones para comprobar permisos. Las permisos personales del propietario de la clave no se heredan por la clave.

Automatización de canal de previsualización

Título de la sección “Automatización de canal de previsualización”

Vincular app_preview solamente a la aplicación de previsualización para CI que crea un canal de previsualización temporal, no público, sube y promueve un paquete, y luego elimina ambos.

{
  "name": "PR preview key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "app_preview",
      "scope_type": "app",
      "org_id": "<OWNING_ORG_UUID>",
      "app_id": "<APP_UUID>"
    }
  ]
}

org_id es la UUID de la organización propietaria de la aplicación. app_id es el UUID interno del registro de la aplicación, no el identificador de aplicación público utilizado por los comandos CLI (por ejemplo, com.example.app) La vinculación sigue siendo organización-vinculada incluso cuando la clave no tiene un rol organización-vinculado.

El nivel de la aplicación app_preview incluye solo app.read, app.read_bundles, app.upload_bundle, y app.create_channel. Cuando esa clave crea un canal, Capgo agrega automáticamente una channel_preview vinculación en el canal creado recientemente. Esa vinculación de hijo concede channel.read, channel.promote_bundle, y channel.delete solo para el canal que la clave creó.

app_preview retiene app.read, por lo que no es una aislación de lectura de canal estricta: la clave puede enumerar los metadatos de canal en la aplicación seleccionada. La vinculación de hijo automática limita mutaciones de ciclo de vida a solo el canal que la clave creó.

Capgo registra la clave de vista previa de la aplicación que subió cada paquete. La clave puede promover solo su propio paquete a cada canal de vista previa que crea. No tiene acceso a las mutaciones de ciclo de vida de un canal existente por defecto/main, un canal creado por otra clave de vista previa o un paquete de otra clave. Para este flujo de trabajo, omita public y nunca utilice --default.

Utilice channel delete <preview-channel> <public-app-id> --delete-bundle para la limpieza. Este es un recorrido de limpieza de vista previa atómica, verificado por propiedad; elimina solo el canal de vista previa de la clave de llamada y el paquete vinculado. app_preview no concede permisos generales bundle.delete.

Para la configuración de la consola y un ejemplo completo de CLI, consulte Utilice una clave de vista previa de aplicación para flujos de trabajo de vista previa.

Un diagrama que explica cómo funcionan los permisos de clave de RBAC API

permisos de organización de creación

Sección titulada “Permiso de creación de organización”

La creación de organizaciones con una clave API ahora utiliza un permiso global explícito: org.create.

Este permiso es separado de las vinculaciones de roles de org/app normales porque una nueva organización no existe aún cuando POST /organization/ se llama. Para crear organizaciones con una clave API:

  • La clave API debe incluir org.create en global_permissions.
  • La misma clave API también debe tener una organización-scoped org_admin o org_super_admin ¿Qué pasa con las claves __CAPGO_KEEP_0__ nuevas que no reciben
  • New API keys do not receive org.create Permitir la creación de organizaciones ¿Qué pasa con las claves __CAPGO_KEEP_0__ nuevas que no reciben por defecto? Activa al crear o editar una clave de RBAC API en la consola.
  • Las claves de administrador de escritura de organización/existente administrador de superusuario API se rellenaron con org.create para que las integraciones existentes puedan seguir creando organizaciones.

Cuando una clave API crea una organización, Capgo asigna automáticamente la misma clave API a org_super_admin en la organización recién creada. Esto permite a la integración gestionar la organización que acaba de crear sin necesitar una vinculación de rol manual separada.

Si crea una clave API a través de API, incluya global_permissions junto con la vinculación de administrador de organización:

{
  "name": "Provisioning key",
  "hashed": true,
  "bindings": [
    {
      "role_name": "org_admin",
      "scope_type": "org",
      "org_id": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "global_permissions": ["org.create"]
}

org.create solo se aplica a la creación de organizaciones. Eliminar una organización sigue requiriendo permiso de eliminación en la organización objetivo, típicamente a través de org_super_admin.

Claves Seguras (Hashed)

Sección titulada “Claves Seguras (Hashed)”

Al crear una clave segura, el servidor genera el material de la clave y devuelve el valor en texto plano una vez. Solo se almacena una hash. Esto significa:

  • La clave de texto plano no se puede recuperar después de la creación.
  • La regeneración produce una nueva clave de texto plano (mostrada una vez) y actualiza el hash almacenado.
  • Se recomiendan las claves hashadas para el uso en producción.

Algunas organizaciones imponen claves hashadas mediante la enforce_hashed_api_keys póliza de la organización.

Vencimiento

Sección titulada “Vencimiento”

Las claves pueden tener una fecha de vencimiento opcional. Las claves vencidas se rechazan en el nivel de verificación de permisos.

Las pólizas de organización pueden imponer:

  • Expiración obligatoria (require_apikey_expiration) — Todas las nuevas claves deben tener una fecha de vencimiento.
  • Tiempo de Vida Máximo (max_apikey_expiration_days) — La fecha de vencimiento no puede ser más allá de N días de ahora.

Prácticas de Seguridad

Sección titulada “Prácticas de Seguridad”
  1. Principio de Menor Privilegio: Asignar el rol más restrictivo que aún permita que tu integración funcione
  2. Rotación Regular: Regenera tus API claves periódicamente utilizando la característica de regeneración
  3. Almacenamiento Seguro: Almacena las API claves de manera segura y nunca las comitas a control de versiones
  4. Uso de Claves HasheadasCrear claves seguras (hash) para integraciones de producción
  5. Establecer ExpiraciónSiempre establecer una fecha de expiración en claves utilizadas para acceso temporal o CI/CD
  6. Restricciones de ÁmbitoRestringir claves a aplicaciones específicas con el rol mínimo requerido

Uso Común

Título de la sección “Uso Común”
  1. Integración CI/CDCrear claves con ámbito específico para aplicaciones con el app_uploader o app_developer Crear claves con ámbito específico para aplicaciones con el rol y establecer una fecha de expiración
  2. Canales de Vista Previa de PR: Utilice app_preview en la aplicación de previsualización o aplicaciones solo cuando la CI necesite subir un paquete, crear un canal temporal y eliminar de forma atómica su propio canal y paquete.
  3. Automatización de Despliegue: Utilice claves con el app_developer rol para scripts de automatización de despliegue.
  4. Herramientas de Monitoreo: Crea claves con el app_reader rol para integraciones de monitoreo externas.
  5. Acceso Administrativo: Utilice claves con el org_admin rol con moderación para herramientas administrativas.
  6. Integraciones de TercerosCrear claves restringidas a aplicaciones específicas con el rol mínimo requerido.
  7. Provisión de OrganizaciónUsar un org_admin o org_super_admin ¿Qué alternativas tenemos? org.create ¿Qué alternativas tenemos?

Keep going from API Keys

Section titled “Keep going from API Keys”

¿Qué alternativas tenemos? Siga desde Claves API Sección titulada Siga desde Claves __CAPGO_KEEP_0__ Si está utilizando Claves capgo para planificar la autenticación y los flujos de cuentas, conecte con @capgo/capacitor-login-social para los detalles de implementación en @capgo/capacitor-login-social, @capgo/capacitor-clave-privada para los detalles de implementación en @capgo/capacitor-clave-privada, @capgo/capacitor-autenticación-biográfica-nativa para los detalles de implementación en @capgo/capacitor-autenticación-biográfica-nativa, Autenticación de dos factores para los detalles de implementación en Autenticación de dos factores, y SSO (Empresas) para los detalles de implementación en SSO (Empresas).