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 basado en rol (RBAC) para un control de acceso fino. Cada clave también puede tener una fecha de vencimiento opcional y se puede crear como una clave “segura” (hashada) donde el valor de texto plano solo se muestra una vez.

Usando una clave API

Utilice el encabezado de autenticación documentado por el endpoint. Para solicitudes de API-clave, authorization se acepta:

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

Algunos puntos finales también aceptan un encabezado de clave dedicado. El Canales API acepta authorization o capgkeyutilice uno de esos encabezados para la automatización de canal de previsualizació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 los permisos básicos de la llave en toda la organización (por ejemplo, org_admin o org_member).
• App roles — Permisos por aplicación (por ejemplo, app_admin, app_developer, app_uploader, app_reader, o app_preview).

Si una clave API tiene vinculaciones de rol explícitas, solo 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

Vincular app_preview solo al aplicativo de previsualización para CI que crea un canal de previsualización temporal, no público, carga 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 público de la aplicación utilizado por los comandos CLI (por ejemplo, com.example.appLa vinculación sigue siendo organización-vinculada incluso cuando la clave no tiene un rol organización-vinculado.

Nivel de la aplicación app_preview incluye solo el rol 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 solamente para el canal que la clave creó.

app_preview retiene app.readNo es una aislación estricta del canal de lectura: la clave puede enumerar metadatos de canal en la aplicación seleccionada. Los límites de vinculación de hijo automática mutaciones de ciclo de vida a los canales 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 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 use --default.

Utilice channel delete <preview-channel> <public-app-id> --delete-bundle para la limpieza. Esta es una ruta de limpieza de vista previa atómica y verificada de propiedad; elimina solo el canal de vista previa del clave llamante 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 Use an App Preview key for preview workflows.

Nota

Claves sin vinculaciones de rol recaen en un sistema basado en modo de legado (read, upload, write, allEstos modos están descontinuados — utilice roles de RBAC en su lugar.

Permiso de creación de organización

Crear organizaciones con una clave API ahora utiliza una permisión global explícita: org.create.

Esta 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 vinculación.
• Las nuevas claves API no reciben org.create por defecto. Habilita Permitir crear organizaciones al crear o editar una clave API de RBAC en la consola.
• Clave de escritura existente para admins/super admins de organización API se completaron con org.create para que las integraciones existentes puedan seguir creando organizaciones.

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

Si crea una API clave a través de API, incluya global_permissions junto con la vinculación de admin 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. La eliminación de una organización sigue requiriendo permiso de eliminación en la organización objetivo, normalmente a través de org_super_admin.

Claves Seguras (Hash)

Cuando se crea una clave segura, el servidor genera el material de la clave y devuelve el valor en texto plano una vez. Solo se almacena una huella. 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 claves hashadas para uso en producción.

Algunas organizaciones obligan a utilizar claves hashadas mediante la enforce_hashed_api_keys org policy.

Vencimiento

Claves pueden tener una fecha de caducidad opcional. Las claves caducadas se rechazan en el nivel de verificación de permisos.

Las políticas de organización pueden obligar a:

• Expiración obligatoria (require_apikey_expiration) — All new keys must have an expiry.
• Maximum TTL (max_apikey_expiration_days — El vencimiento no puede ser más allá de N días desde ahora.

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 SeguroAlmacene las llaves API de manera segura y nunca las comití en control de versiones
4. Uso de Claves Hasheadas: Crea claves seguras (hasheadas) para integraciones de producción
5. Establecer Expiración: Siempre establece una fecha de expiración en las claves utilizadas para acceso temporal o acceso CI/CD
6. Restricciones de Ámbito: Restringe claves a aplicaciones específicas con el rol mínimo requerido

Casos de uso comunes

1. Integración CI/CD: Crea claves escopadas a aplicaciones específicas con el app_uploader o app_developer rol y establecer una fecha de expiración.
2. Canales de Previsualización de PR: Utilice app_preview solo en la aplicación de previsualización o aplicaciones cuando CI necesita subir un paquete, cree un canal temporal y limpie atómicamente su propio canal y paquete.
3. Automatización de la implementación: Utilice claves con el app_developer rol para scripts de implementación automatizados.
4. Herramientas de monitoreo: Cree claves con el app_reader rol para integraciones de monitoreo externas.
5. Acceso administrativo: Utilice claves con el org_admin utiliza con moderación para herramientas administrativas.
6. Integraciones de terceros: Cree claves restringidas a aplicaciones específicas con el rol mínimo requerido.
7. Provisión de Organización: Utilice un org_admin o org_super_admin Clave de RBAC con org.create solo para automatización confiable que necesita crear organizaciones.

Siga adelante desde Claves API

Si está utilizando Claves __CAPGO_KEEP_0__ Claves de API conectarlo para planificar flujos de autenticación y cuentas @capgo/capacitor-login-social Para los detalles de implementación en @capgo/capacitor-login-social. @capgo/capacitor-clave de acceso para la implementación en @capgo/capacitor-passkey @capgo/capacitor-nativo-biometria para la implementación en @capgo/capacitor-native-biometric Autenticación en dos factores para la implementación en la autenticación en dos factores, y SSO (Empresas) para la implementación en SSO (Empresas).