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 rol para un control de acceso fino. 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 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 administrar 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 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 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 (read, upload, write, all). Estos modos están descontinuados — utilice roles RBAC en su lugar.

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 hashadas para el uso en producción.

Algunas organizaciones imponen llaves hashadas 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 desde ahora.

Prácticas de seguridad recomendadas

1. Principio de Menor Privilegio: Asigna el rol más restrictivo que aún permita 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: Almacene las API claves de manera segura y nunca las comunique a control de versiones
4. Use Keys con Hash: Cree claves seguras (hash) para integraciones de producción
5. Vencimiento: Establezca siempre una fecha de vencimiento en las claves utilizadas para acceso temporal o CI/CD
6. Restricciones de Ámbito: Restrinja las claves a aplicaciones específicas con el rol mínimo requerido

Uso Común

1. Integración CI/CD: Cree claves con ámbito específico para aplicaciones con app_uploader o app_developer rol y establecer una fecha de caducidad
2. Automatización de Despliegue: Utilice claves con el app_developer rol para scripts de despliegue automatizados
3. Herramientas de Monitoreo: Crea 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: Crea claves restringidas a aplicaciones específicas con el rol mínimo requerido