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 basado en rol (RBAC) para un control de acceso fino. Cada clave también puede tener una fecha de caducidad opcional y se puede crear como una clave “segura” (hashada) donde el valor en texto plano solo se muestra una vez.

Usando una API clave

Pase su API clave en el x-api-key encabezado de cada solicitud:

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

El authorization encabezado también se acepta, pero está principalmente destinado a tokens JWT. Cuando el valor es una clave de UUID formateada API funciona, pero x-api-key es el encabezado recomendado para todos los tipos de claves (incluidas las claves seguras/hashadas).

Permisos de RBAC

Los 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, asigna roles a dos niveles:

• Rol de organización — Define las permisos básicos de la clave en 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 esas vinculaciones son evaluadas para los controles de permisos. Los permisos personales del propietario de la clave no se heredan por la clave.

Nota

Las claves sin vinculación de roles recaen en un sistema basado en modo heredado (read, upload, write, all). Estos modos están descontinuados — utilice roles de RBAC en su lugar.

Claves Seguras (Hashed)

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

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

Algunas organizaciones imponen claves hashadas mediante el 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.
• 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 Privilegios Mínimos: Asigne el rol más restrictivo que aún permita que tu integración funcione
2. Rotación Regular: Rota tus API periódicamente utilizando la característica de regeneración
3. Almacenamiento Seguro: Almacena API de manera segura y nunca los comitas a control de versiones
4. Usar Claves Hasheadas: Crea claves seguras (hasheadas) para integraciones de producción
5. Establecer Vencimiento: Establece siempre una fecha de vencimiento en claves utilizadas para acceso temporal o acceso 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: Crea claves vinculadas a aplicaciones específicas con el app_uploader o app_developer rol, y establece una fecha de expiración
2. Automatización de Despliegue: Utiliza 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 de Administrador: Use keys with el org_admin role con moderación para herramientas administrativas
5. Integraciones de Terceros: Crea claves restringidas a aplicaciones específicas con el rol mínimo requerido

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 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 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).