Claves de API

Las claves API se usan para autenticar solicitudes a la Capgo API. Las claves son específicas de la organización y se les pueden asignar roles RBAC para un control de acceso granular. Cada clave también puede tener una fecha de expiración opcional y se puede crear como una clave “secure” (hasheada), donde el valor en texto plano solo se muestra una vez.

Uso de una key de API

Usa el header de autenticación documentado por el endpoint. Para peticiones con clave API, authorization se acepta:

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

Algunos endpoints también aceptan un header de clave dedicado. El Canales API acepta authorization o capgkey; usa uno de esos headers para la automatización del preview-channel.

Permisos RBAC

Las claves de API utilizan el mismo sistema de control de acceso basado en roles (RBAC) que las cuentas de usuario. Al crear o gestionar claves mediante la web app o API, asignas roles en dos niveles:

• Rol de la organización — Define los permisos base de la clave en toda la organización (por ejemplo, org_admin o org_member).
• Roles de la app — Permisos por app (por ejemplo, app_admin, app_developer, app_uploader, app_reader, o app_preview).

Si una clave de API tiene asignaciones de rol explícitas, solo esas asignaciones se evalúan para las comprobaciones de permisos. La clave no hereda los permisos personales de su propietario.

Automatización de canales de preview

Vincular app_preview solo a la app de preview para CI que crea un canal de preview temporal y no público, sube y promociona un bundle 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 el UUID de la organización propietaria de la app. app_id es el UUID interno del registro de la app, no el identificador público de la app que usan los comandos de CLI (por ejemplo, com.example.app). El binding sigue vinculado a la organización, incluso si la clave no tiene un rol a nivel de organización.

La app-level app_preview el rol incluye solo app.read, app.read_bundles, app.upload_bundle, y app.create_channel. Cuando esa clave crea un canal, Capgo añade automáticamente un channel_preview binding en el canal recién creado. Ese binding hijo otorga channel.read, channel.promote_bundle, y channel.delete solo para el canal que la clave creó.

app_preview mantiene app.read, por lo que no es un aislamiento estricto de lectura de canales: la clave puede enumerar metadatos de canales en la app seleccionada. El binding hijo automático limita mutaciones de ciclo de vida al canal que la clave creó.

Capgo registra la clave de App Preview que subió cada bundle. La clave solo puede promover su propio bundle a cada canal de preview que cree. No tiene acceso al ciclo de vida de un canal default/main existente, de un canal creado por otra clave de preview, ni de un bundle de otra clave. Para este flujo, omite public y nunca uses --default.

Usa channel delete <preview-channel> <public-app-id> --delete-bundle para la limpieza. Esta es una ruta de limpieza de preview atómica y con verificación de propiedad; elimina solo el canal de preview de la clave que llama y el bundle vinculado. app_preview no otorga acceso genérico bundle.delete.

Para configurar el dashboard y ver un ejemplo completo de CLI, consulte Usa una clave de App Preview para workflows de preview.

Nota

Las claves sin role bindings recurren a un sistema heredado basado en modos (read, upload, write, all). Estos modos están obsoletos; usa roles RBAC en su lugar.

Permiso de creación de organización

Crear organizaciones con una clave API ahora usa un permiso global explícito: org.create.

Este permiso es independiente de los role bindings normales de org/app porque la nueva organización aún no existe 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 de API también debe tener un alcance de organización actual org_admin o org_super_admin binding.
• Las nuevas claves API no reciben org.create por defecto. Activa Permitir crear organizaciones al crear o editar una clave API con RBAC en el dashboard.
• Las claves API existentes de admin de organización/super admin con permisos de escritura se rellenaron con org.create para que las integraciones actuales puedan seguir creando organizaciones.

Cuando una clave API crea una organización, Capgo asigna automáticamente esa misma clave API 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 necesidad de asignar roles manualmente.

Si creas una clave de API a través de API, incluye global_permissions junto al vínculo del administrador de la 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 de destino, normalmente a través de org_super_admin.

Keys seguras (hasheadas)

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

• La clave en texto plano no puede recuperarse después de su creación.
• La regeneración crea una nueva clave en texto plano (se muestra una sola vez) y actualiza el hash almacenado.
• Se recomienda usar claves hasheadas en producción.

Algunas organizaciones aplican claves con hash mediante la enforce_hashed_api_keys org policy.

Expiración

Las claves pueden tener una fecha de expiración opcional. Las claves expiradas se rechazan en la capa de verificación de permisos.

Las políticas de la organización pueden aplicar:

• Expiración obligatoria (require_apikey_expiration) — All new keys must have an expiry.
• TTL máximo (max_apikey_expiration_days) — La expiración no puede ser posterior a N días a partir de ahora.

Mejores prácticas de seguridad

1. Principio de mínimo privilegio: Asigna el rol más restrictivo que permita que tu integración funcione
2. Rotación periódica: Rota tus claves de API periódicamente usando la función de regeneración
3. Almacenamiento seguro: Almacena las claves de API de forma segura y no las commitees al control de versiones
4. Usa claves hasheadas: Crea claves seguras (hasheadas) para integraciones de producción
5. Establece caducidad: Establece siempre una fecha de caducidad en las claves usadas para acceso temporal o CI/CD
6. Restricciones de alcance: Restringe las claves a aplicaciones específicas con el rol mínimo requerido

Casos de uso comunes

1. Integración CI/CD: Crea claves con alcance limitado a aplicaciones específicas con el app_uploader o app_developer rol, y establece una fecha de expiración.
2. Canales de vista previa de PR: Usa app_preview solo en la app de preview o en las apps cuando CI necesita subir un bundle, crear un canal temporal y limpiar de forma atómica su propio canal y bundle.
3. Automatización de despliegues: Usa claves con el app_developer rol para scripts de despliegue automatizados.
4. Herramientas de monitoreo: Crea claves con el app_reader rol para integraciones de monitoreo externas.
5. Acceso de administrador: Usa claves con el org_admin rol con moderación para herramientas administrativas.
6. Integraciones de terceros: Crea claves restringidas a apps específicas con el rol mínimo necesario.
7. Aprovisionamiento de organización: Usa una org_admin o org_super_admin clave RBAC con org.create solo para automatizaciones de confianza que necesiten crear organizaciones.

Continuar con las Keys de API

Si estás usando Claves de API para planificar los flujos de autenticación y de cuenta, conéctalo con @capgo/capacitor-social-login para los detalles de implementación en @capgo/capacitor-social-login, @capgo/capacitor-passkey para el detalle de implementación en @capgo/capacitor-passkey, @capgo/capacitor-native-biometric para el detalle de implementación en @capgo/capacitor-native-biometric, Autenticación de dos factores para el detalle de implementación en la autenticación de dos factores, y SSO (Empresa) para el detalle de implementación en SSO (Enterprise).