API Claves

Las API claves se utilizan para autenticar solicitudes a la Capgo API. Las claves son específicas de la organización y se pueden asignar roles de acceso de 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

Pasa tu 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á destinado principalmente 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

Las 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 vinculaciones de roles recaen en un sistema basado en modo de legado (read, upload, write, allEstos modos están descontinuados — utilice roles de RBAC en su lugar.

Permiso de creación de organización

La creación de organizaciones con una clave API ahora utiliza un permiso global explícito: org.create.

Este permiso es separado de las vinculaciones de roles normales de org/app porque una nueva organización no existe aún cuando se llama. POST /organization/ 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 una vinculación organización-escopada org_admin o org_super_admin de
• Nuevas claves API no reciben org.create por defecto. Habilita Permitir crear organizaciones al crear o editar una clave de RBAC API en la consola.
• Existing write-capable org admin/super admin API keys were backfilled with org.create para que las integraciones existentes 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 a la integración gestionar la organización que acaba de crear sin necesidad de una vinculación de rol manual separada.

Si crea una clave API a través de API, incluya global_permissions junto con la vinculación de administrador de 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 aplica solo a la creación de organizaciones. La eliminación de una organización sigue requiriendo permiso de eliminación en la organización objetivo, típicamente a través de org_super_admin.

Claves Seguras (Hasheadas)

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

• La llave de texto plano no se puede recuperar después de la creación.
• La regeneración produce una nueva llave de texto plano (mostrada una vez) y actualiza la hash almacenada.
• Se recomiendan 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 de ahora.

Mejores prácticas de seguridad

1. Principio de Menor Privilegio: Asigne el rol más restrictivo que aún permita que su integración funcione
2. : Regenerar periódicamente sus __CAPGO_KEEP_0__ claves 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. Expiración: Establezca siempre una fecha de expiración 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
6. Provisión de Organizaciones: Utilice un org_admin o org_super_admin clave de RBAC con org.create solo para automatización confiable que necesite crear organizaciones

Siga adelante desde API Claves

Si está utilizando API Claves para planificar flujos de autenticación y cuentas, conéctelo 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).