Claves de API

Las llaves API se usan para autenticar peticiones a la API Capgo. Las llaves son específicas de la organización y pueden tener roles RBAC para un control de acceso granular. Cada llave puede incluir una fecha de expiración opcional y crearse como una llave “secure” (hasheada), donde el valor en texto plano solo se muestra una vez.

Uso de una clave 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 llaves de API usan el mismo sistema de control de acceso basado en roles (RBAC) que las cuentas de usuario. Al crear o gestionar llaves desde la web app o API, asignas roles en dos niveles:

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

Si una llave de API tiene roles vinculados explícitamente, solo esos vínculos se evalúan para los controles de permisos. La llave no hereda los permisos personales del propietario.

Automatización del canal de preview

Vincula app_preview solo para la app de preview de CI que crea un canal de preview temporal y privado, sube y promociona un bundle, y luego los elimina.

{
  "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 usado por los comandos de CLI (por ejemplo, com.example.app). El vínculo permanece ligado a la organización, incluso si la clave no tiene un rol a nivel organizacional.

El nivel de app 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 creó la clave.

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

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 canales en un canal principal/default existente, en un canal creado por otra clave de preview, ni al 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 previews atómica con verificación de propiedad; solo elimina el preview channel y el bundle vinculado de la clave que realiza la llamada. app_preview no otorga acceso genérico bundle.delete.

Para la configuración del dashboard y un ejemplo completo de CLI, consulta Usa una clave de App Preview para flujos de preview.

Nota

Las claves sin roles asignados 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 las asignaciones de roles normales de org/app porque una nueva organización aún no existe cuando POST /organization/ se invoca. 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 un ámbito de organización vigente org_admin o org_super_admin binding.
• Las nuevas claves API no reciben org.create por defecto. Activa Permitir la creación de organizaciones al crear o editar una clave API con RBAC en el dashboard.
• Las claves API existentes de admin/super admin con permisos de escritura se actualizaron 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 un binding de rol manual.

Si creas una clave API a través de API, incluye global_permissions junto con la vinculación del admin de la 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 solo aplica al crear organizaciones. Borrar una organización requiere permisos de borrado en la org de destino, normalmente mediante org_super_admin.

Claves seguras (hasheadas)

Al crear una secure key, 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 se puede recuperar después de su creación.
• La regeneración genera una nueva clave en texto plano (que se muestra una vez) y actualiza el hash almacenado.
• Se recomiendan las hashed keys para entornos de producción.

Algunas organizaciones exigen claves con hash a través de la enforce_hashed_api_keys org policy.

Expiración

Las keys pueden tener una fecha de expiración opcional. Las keys 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 mayor a N días a partir de ahora.

Buenas prácticas de seguridad

1. Principio de menor privilegio: Asigna el rol más restrictivo que permita el funcionamiento de tu integración
2. Rotación regular: Rota tus claves API periódicamente usando la función de regeneración
3. Almacenamiento seguro: Guarda las claves API de forma segura y nunca las subas al control de versiones
4. Usa claves con hash: Crea claves seguras (hashed) para integraciones en producción
5. Establecer expiración: Define siempre una fecha de expiración en las claves para acceso temporal o CI/CD
6. Restricciones de alcance: Restringe las claves a apps específicas con el rol mínimo necesario

Casos de uso comunes

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

Continuar desde API Keys

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