Claves API

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 control de acceso basado en roles (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

Pasa tu API clave en la x-api-key cabecera de cada solicitud:

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

La authorization cabecera también se acepta, pero está principalmente destinada a tokens JWT. Cuando el valor es una clave API formateada como UUID, funciona, pero x-api-key es la cabecera recomendada para todos los tipos de claves (incluidas las claves seguras/hasheadas).

Permisos de RBAC

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

• Rol de organización — Define la clave de permisos base para toda la organización (por ejemplo, org_admin, org_member).
• Roles de la aplicación — Permisos opcionales por aplicación (por ejemplo, app_admin, app_developer, app_uploader, app_reader).

Si una clave API tiene vinculaciones de roles explícitas, solo se evalúan esas vinculaciones para las comprobaciones de permisos. Los permisos personales del propietario de la clave no se heredan de la clave.

Nota

Las claves sin vinculaciones de roles recaen en un sistema basado en modos deprecado (read, upload, write, all). Se recomienda usar roles RBAC en lugar de estos modos.

Claves seguras (hasheadas)

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

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

Algunas organizaciones imponen llaves hash mediante la enforce_hashed_api_keys política de la organización.

Vencimiento

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

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

• Expiración obligatoria (require_apikey_expiration) — Todas las nuevas claves deben tener una fecha de vencimiento.
• TTL 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 recomendadas

1. Principio de Menor Privilegio: Asignar el rol más restrictivo que aún permite que tu integración funcione
2. : Regenera tus __CAPGO_KEEP_0__ claves periódicamente utilizando la característica de regeneración: Rotate your API keys periodically using the regenerate feature
3. Principio de Menor Privilegio: Asigna el rol más restrictivo que aún permite que tu integración funcione: Almacene las API claves de manera segura y nunca las comunique a control de versiones
4. Use Keys Hashed: Cree claves seguras (hash) para integraciones de producción
5. Establecer Vencimiento: Establezca siempre una fecha de vencimiento en las claves utilizadas para acceso temporal o CI/CD
6. Restricciones de Ámbito: Restringe claves a aplicaciones específicas con el rol mínimo requerido

Uso Común

1. Integración CI/CD: Cree claves con ámbito a aplicaciones específicas con el app_uploader o app_developer rol y establecer una fecha de expiración
2. Automatización de Despliegue: Utilice claves con el app_developer rol para scripts de despliegue automatizados
3. Herramientas de Monitoreo: Cree claves con el app_reader rol para integraciones de monitoreo externas
4. Acceso Administrativo: Utilice claves con el org_admin rol con moderación para herramientas administrativas
5. Integraciones de Terceros: Cree claves restringidas a aplicaciones específicas con el rol mínimo requerido