API Claves

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

Usando una clave API

Utilice el encabezado de autenticación documentado por el punto final. Para solicitudes con claves API, 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 capgkeyUse 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 la organización — Define las permisos básicos de la llave en toda la organización (por ejemplo, org_admin o org_member).
• Roles de la aplicación — Permisos por aplicación (por ejemplo, app_admin, app_developer, app_uploader, app_reader, o app_preview).

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

Automación del canal de vista previa

Unir app_preview solamente a la aplicación de vista previa para CI que crea un canal de vista previa temporal y 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 CLI comandos (por ejemplo, com.example.appLa vinculación permanece ligada a la organización incluso cuando la clave no tiene un rol organizativo.

El rol de nivel de aplicación incluye solo app_preview , y app.read, app.read_bundles, app.upload_bundleEl rol de nivel de aplicación incluye solo app.create_channelWhen ese clave crea un canal, Capgo agrega automáticamente una channel_preview vinculación en el canal creado recientemente. Esa vinculación secundaria concede channel.read, channel.promote_bundle, y channel.delete solamente para el canal que la clave creó.

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

Capgo registra la clave de vista previa de App que subió cada paquete. La clave puede promover solo su propio paquete a cada canal de vista previa que crea. No tiene acceso a la vida de ciclo de canal 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.

Use channel delete <preview-channel> <public-app-id> --delete-bundle para eliminar. Este es un recorrido de eliminación de vista previa atómica y verificado por propiedad; elimina solo el canal de vista previa y el paquete vinculado de la clave que llama. app_preview No concede permisos generales bundle.delete.

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

Nota

Las claves sin vinculaciones de rol recaen en un sistema basado en modo (read, upload, write, all). Estos 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 un permiso global explícito: org.create.

Este permiso es separado de las vinculaciones de rol normales de org/app porque una nueva organización no existe aún cuando se crea un __CAPGO_KEEP_0__ 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 actualizada org_admin o org_super_admin vinculación.
• Las nuevas claves API no reciben org.create por defecto. Habilita Permitir crear organizaciones cuando se crea o edita una clave de RBAC API en la consola.
• Existing write-capable org admin/super admin API keys were backfilled with org.create para que las integraciones existentes puedan seguir creando organizaciones.

When un 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 rol manual separada.

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

{
  "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 aplica solo a la creación de organizaciones. La eliminación de 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 (Hasheadas)

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 en 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 la hash almacenada.
• Se recomiendan claves hashadas para uso en producción.

Algunas organizaciones imponen claves hashadas mediante la enforce_hashed_api_keys política de la organización.

Vencimiento

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

Las políticas de organización pueden imponer:

• Expiración obligatoria (require_apikey_expiration) — Todas las nuevas claves deben tener una fecha de vencimiento.
• ) — El vencimiento no puede ser más allá de N días desde hoy. (max_apikey_expiration_daysorg policy

Prácticas de Seguridad

1. Principio de Menor Privilegio: Asigne el rol más restrictivo que aún permita que su integración funcione
2. Rotación Regular: Rota sus API periódicamente utilizando la característica de regeneración
3. Almacenamiento Seguro: Almacene sus API claves de manera segura y nunca las comita a control de versiones
4. Uso de Claves Hasheadas: Cree claves seguras (hasheadas) para integraciones de producción
5. Establecer Expiración: Establezca siempre una fecha de expiración en claves utilizadas para acceso temporal o acceso CI/CD
6. Restricciones de Ámbito: Restringir claves a aplicaciones específicas con el rol mínimo requerido

Uso Común

1. Integración CI/CD: Crear 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: Utilizar app_preview solo en la aplicación de previsualización o aplicaciones cuando se necesite subir un paquete, crear un canal temporal y eliminar automáticamente su propio canal y paquete.
3. Automatización de Despliegue: Utilice claves con el app_developer role para scripts de despliegue automatizado.
4. Herramientas de Monitoreo: Crea claves con el app_reader role para integraciones de monitoreo externo.
5. Acceso Administrativo: Utilice claves con el org_admin role con moderación para herramientas administrativas.
6. Integraciones de Terceros: Crea 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 llave de RBAC con org.create solo para automatización confiable que necesita crear organizaciones.

Sigue adelante desde API Claves

Si estás utilizando API Claves para planificar flujos de autenticación y cuentas, conecta con @capgo/capacitor-login-social para los detalles de implementación en @capgo/capacitor-login-social, @capgo/capacitor-passkey para los detalles de implementación en @capgo/capacitor-passkey, @capgo/capacitor-nativo-biometrico para el detalle de implementación en @capgo/capacitor-nativo-biometrico, Autenticación en dos factores para el detalle de implementación en Autenticación en dos factores, y SSO (Empresas) para el detalle de implementación en SSO (Empresas).